TwinCollection Class

Representation of a single Twin collection for Provisioning.

The TwinCollection is an extension of a HashMap of String and Object that contain individual and general versioning mechanism.

By the Twin definition, the Object can contain types of Boolean, Number, String, Object, or a sub-TwinCollection, but it cannot be types defined by the user or arrays.

A TwinCollection can contain up to 5 levels of sub TwinCollections. Once the TwinCollection is a extension of the HashMap, both TwinCollection as well as its sub-TwinCollections can be casted to Map of String and Object.

The collection will be represented in the rest API as a JSON in the body. It can or cannot contain the metadata (identified by the $ character at the beginning of the key.

Because of the Twin metadata, the character $ is not allowed in the entry key.

For instance, the following JSON is a valid TwinCollection with its metadata.

{
     "Color":"White",
     "MaxSpeed":{
         "Value":500,
         "NewValue":300
     },
     "$metadata":{
         "$lastUpdated":"2017-09-21T02:07:44.238Z",
         "$lastUpdatedVersion":4,
         "Color":{
             "$lastUpdated":"2017-09-21T02:07:44.238Z",
             "$lastUpdatedVersion":4,
         },
         "MaxSpeed":{
             "$lastUpdated":"2017-09-21T02:07:44.238Z",
             "$lastUpdatedVersion":4,
             "Value":{
                 "$lastUpdated":"2017-09-21T02:07:44.238Z",
                 "$lastUpdatedVersion":4
             },
             "NewValue":{
                 "$lastUpdated":"2017-09-21T02:07:44.238Z",
                 "$lastUpdatedVersion":4
             }
         }
     },
     "$version":4
 }

This class exposes the Twin collection with or without metadata as a Map here user can gat both the value and the metadata. For instance, in the above TwinCollection, #get(Object) for Color will return White and the getTwinMetadata(String key) for Color will return the Object TwinMetadata that contain getLastUpdated() that will returns the Date 2017-09-21T02:07:44.238Z and getLastUpdatedVersion() that will returns the Integer 4.

For the nested TwinCollection, you can do the same, for instance, the following code will return the value and metadata of the NewValue nested in MaxSpeed:

// Get the value of the MaxSpeed, which is a inner TwinCollection.
      TwinCollection innerMaxSpeed = (TwinCollection) twinCollection.get("MaxSpeed");

      // From the inner TwinCollection, get the value of the NewValue.
      Long maxSpeedNewValue = innerMaxSpeed.get("NewValue");

      // As in the root TwinCollection, the inner TwinCollection contain its own metadata.
      // So, get the metadata information for the inner NewValue.
      TwinMetadata maxSpeedNewValueMetadata = innerMaxSpeed.getTwinMetadata("NewValue");
      Date newValueLastUpdated = maxSpeedNewValueMetadata.getLastUpdated(); //Shall contain `2017-09-21T02:07:44.238Z`
      Integer newValueLastUpdatedVersion = maxSpeedNewValueMetadata.getLastUpdatedVersion(); //Shall contain `4`