TwinCollection Class

Package:

com.microsoft.azure.sdk.iot.provisioning.service.configs

Maven Artifact:

com.microsoft.azure.sdk.iot.provisioning:provisioning-service-client:1.7.0

• java.lang.Object
• • java.util.AbstractMap
  • • java.util.HashMap
    • • com.microsoft.azure.sdk.iot.provisioning.service.configs.TwinCollection

public class TwinCollection
extends java.util.HashMap<java.lang.String,java.lang.Object>

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`

Constructor Summary

Constructor	Description
TwinCollection()	Constructor
TwinCollection(Map<? extends String,Object> map)	Constructor

Method Summary

Modifier and Type	Method and Description
TwinMetadata	getTwinMetadata() Getter for the TwinCollection metadata
TwinMetadata	getTwinMetadata(String key) Getter for the entry metadata in the TwinCollection.
java.lang.Integer	getVersion() Getter for the version.
java.lang.Object	put(String key, Object value) Add a single new entry in the TwinCollection.
void	putAll(Map<? extends String,?> map) Add all information in the provided Map to the TwinCollection.
com.google.gson.JsonElement	toJsonElement() Serializer

Methods inherited from java.lang.Object

java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Methods inherited from java.util.AbstractMap

java.util.AbstractMap.equals java.util.AbstractMap.hashCode java.util.AbstractMap.toString

Methods inherited from java.util.HashMap

java.util.HashMap.clear java.util.HashMap.clone java.util.HashMap.compute(K,java.util.function.BiFunction< java.util.HashMap.computeIfAbsent(K,java.util.function.Function< java.util.HashMap.computeIfPresent(K,java.util.function.BiFunction< java.util.HashMap.containsKey java.util.HashMap.containsValue java.util.HashMap.entrySet java.util.HashMap.forEach(java.util.function.BiConsumer< java.util.HashMap.get java.util.HashMap.getOrDefault java.util.HashMap.isEmpty java.util.HashMap.keySet java.util.HashMap.merge(K,V,java.util.function.BiFunction< java.util.HashMap.put java.util.HashMap.putAll(java.util.Map< java.util.HashMap.putIfAbsent java.util.HashMap.remove java.util.HashMap.remove java.util.HashMap.replace java.util.HashMap.replace java.util.HashMap.replaceAll(java.util.function.BiFunction< java.util.HashMap.size java.util.HashMap.values

Constructor Details

TwinCollection

public TwinCollection()

Constructor

Creates an empty collection. Fill it with put(String key, Object value) or putAll(Map<? extends String,?> map).

TwinCollection

public TwinCollection(Map map)

Constructor

Creates a new Twin collection coping the provided Map. Once TwinCollection extends Map, this method can copy another TwinCollection.

Parameters:

map - the Map of ? extends String and Object with the Twin collection

Method Details

getTwinMetadata

public TwinMetadata getTwinMetadata()

Getter for the TwinCollection metadata

Returns:

the TwinMetadata of the Whole TwinCollection. It can be null.

getTwinMetadata

public TwinMetadata getTwinMetadata(String key)

Getter for the entry metadata in the TwinCollection.

Parameters:

key - the String with the name of the entry to retrieve the metadata.

Returns:

the TwinMetadata ot the specific entry in the TwinCollection. It can be null.

getVersion

public Integer getVersion()

Getter for the version.

Returns:

The Integer with the version content. It can be null.

put

public Object put(String key, Object value)

Add a single new entry in the TwinCollection.

Override HashMap.put(String, Object).

This function will add a single pair key value to the TwinCollection. By the Twin definition, the Object can contain types of Boolean, Number, String, Object, or up to 5 levels of sub-TwinCollection, but it cannot be types defined by the user or arrays.

Overrides:

TwinCollection.put(String key, Object value)

Parameters:

key - the String that represent the key of the new entry. It cannot be {#code null} or empty.

value - the Object that represents the value of the new entry. It cannot be user defined type or array.

Returns:

The Object that correspond to the last value of this key. It will be null if there is no previous value.

putAll

public void putAll(Map map)

Add all information in the provided Map to the TwinCollection.

Override HashMap.putAll(Map).

This function will add all entries in the Map to the TwinCollection. If the provided key already exists, it will replace the value by the new one. This function will not delete or change the content of the other keys in the Map.

As defined by the Twin, the value of a entry can be an inner Map. TwinCollection will accept up to 5 levels of inner Maps.

Overrides:

TwinCollection.putAll(Map<? extends String,?> map)

Parameters:

map - A Map of entries to add to the TwinCollection.

toJsonElement

public JsonElement toJsonElement()

Serializer

Creates a JsonElement, which the content represents the information in this class and its subclasses in a JSON format.

This is useful if the caller will integrate this JSON with JSON from other classes to generate a consolidated JSON.

Returns:

The JsonElement with the content of this class.