Backable Encapsulators


Introduction

Encapsulators are queues with extended functionality. As the name suggests, encapsulators are used to encapsulate data in them, they let the telemonitoring system store data. These encapsulators enable the telemonitoring system to get callbacks on the event that a data point is added or removed, the encapsulator became empty or full and more. Furthermore, encapsulators are backable, allowing them to get support from our backup cabinets for background backup and restoration capabilities. Finally, encapsulators are thread-safe.The PrivacyMechanism mPDI object is used for protecting client sensitive data.

In this tutorial, we demonstrate the basic functionality, handling and capabilities of backable encapsulators.

Basic functionality and handling

Encapsulators allow telemonitoring applications to store data, where each data point has a unique serial number (unique among all other data points in the same encapsulator). Encapsulators support having maximum capacity as well (which by default is infinity). Encapsulators are generic data structures with the generic type T being the type of the data to be stored in the encapsulator.

Since encapsulators are also backable data structures, every encapsulator must be identified by a backable identifier. These identifiers are used for purposes of book keeping should the backable need to be backed up or restore from previous backup. Let’s create an identifier called dataID  using the standard string encapsulator identifier (BackableEncapsulatorIdentifier) as follows:  BackableEncapsulatorIdentifier dataID = new BackableEncapsulatorIdentifier("my data");

The constructor BackableEncapsulator(dataID) is used to initialize an encapsulator, identifier by dataID, with infinite capacity, whereas the constructor  BackableEncapsulator(dataID, cap) is used to initialize an encapsulator, identified by dataID with capacity cap.

Adding data

Once an encapsulator has been created, you can use  addData(T datapoint) to add the data in  datapoint to the encapsulator. This method will return the serial number of the data point inside the encapsulator if it succeeds. The method will throw an IllegalStateException if the encapsulator is full.

Adding data (sensitive data)

For adding sensitive data to the encapsulator created, you can use addData(T datapoint, PrivateClass c)  to add the sanitized data in  datapoint to the encapsulator. This method will return the serial number of the data point inside the encapsulator if it succeeds. The method will throw IllegalStateException  if the encapsulator is full; PrivacyMechanismException  if the input PrivateClass  is not in the predefined category list in the PrivacyMechanism ; NullPointerException  if the Privacy Mechanism mPDI object is null.

Removing data

There are multiple ways that can be used to remove data from the encapsulator. One option is to remove the item in the head of the queue by using popFirst() or popFirst(PrivateClass c) . The popFirst()  can return insensitive data without PrivateMechanism  from the encapsulator. The popFirst(PrivateClass c) can return desanitized data from the encapsulator. If the encapsulator is empty, the method will throw an IllegalStateExceptionIf the input PrivateClass  is not in the predefined category list in the PrivacyMechanism , the method will throw a PrivacyMechanismException . If the the PrivateMechanism mPDI object is null, i.e. the data belongs to sensitive data but calling popFirst(PrivateClass c) , the method will throw a NullPointerException Otherwise, the popFirst() or popFirst (PrivateClass c) method will remove the first data point from the encapsulator and return the original data or desanitized data along with its serial number in a data serial pair object of type DataSerialPair<T>.

Another way to remove a data point from an encapsulator is by using its serial number. This can be done by using  removeData(long serialNumber), which will throw an IllegalStateException if the serial number serialNumber does not exist in the encapsulator. Otherwise, the method will remove the data point associated with the serial number serialNumber.

Finally, the method flushData() can be used to remove all data points from the encapsulator at once.

Retrieving a data point

There are two main ways to retrieve a data point from an encapsulator. The first way is by using getFirst() for insensitive data or getFirst(PrivateClass c)  for sensitive data, which returns a DataSerialPair<T> object representing the head (first data point) of the encapsulator if the encapsulator is not empty. Otherwise, the method will throw an IllegalStateException.

Alternatively, the method getDatapoint(long serialNumber) will return the data point (directly as type T, not DataSerialPair<T>) corresponding to the serial number serialNumber, if it exists. Otherwise, the method will throw an IllegalStateExceptionSimilarly, getDatapoint(long serialNumber, PrivateClass c)  will return the desanitized data point as type T  corresponding to the serial number serialNumber . If the PrivateClass c is not in the predefined category list in the PrivacyMechanism , the method will throw a PrivacyMechanismException . If the Privacy mechanism mPDI  object is null, the method will throw a NullPointerException .

Iterating over the data

The encapsulator is an iterable class. This means that you can iterate over all the data points in the encapsulator by using a for loop as follows. The returned datapoints from an iterator are not desanitized, they’re returned as is

PrivacyMechanism

The PrivacyMechanism  is an  mPDI  object associated with the class BackableEncapsulator  (only mandatory for client sensitive data). We create the mPDI  object using PrivacyMechanismInterface  which represents the  PrivacyMechanism  structure. The PrivacyMechanism  structure includes sanitize method  sanitize(PrivateClass c, T original)  and  desanitize method  desanitize(PrivateClass c, T sanitized). Both methods can manipulate data points of generic type T based on the PrivateClass c .

The sanitizate represents the process of encoding data and the desanitize method represents the process of decoding data using Privacy Mapping Functions (PMF) which are generated by a computational software MATLAB. The MATLAB implements as a toolbox. The PMF can shuffle the  categories of the sensitive data in the class BackableEncapsulator .

Example of basic functionality

Testing code without privacy mechanism together, consider the output of the following code:

What would this code print?

Testing code with privacy mechanism together, consider the output of the following code:

What would this code print?

 

 

 

Basic capabilities

Events (TODO: finish)