TwinCollection (Dependencies for Iot Hub Java SDK 0.8.3 API)

java.lang.Object
- java.util.AbstractMap<K,V>
- - java.util.HashMap<String,Object>
  - - com.microsoft.azure.sdk.iot.deps.twin.TwinCollection

All Implemented Interfaces:

Serializable, Cloneable, Map<String,Object>
```
public class TwinCollection
extends HashMap<String,Object>
```
Representation of a single Twin collection.
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, HashMap.get(Object) for Color will return White and the getTwinMetadataFinal(String) for Color will return the Object TwinMetadata that contain TwinMetadata.getLastUpdated() that will returns the Date 2017-09-21T02:07:44.238Z and TwinMetadata.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.getTwinMetadataFinal("NewValue");
      Date newValueLastUpdated = maxSpeedNewValueMetadata.getLastUpdated(); //Shall contain `2017-09-21T02:07:44.238Z`
      Integer newValueLastUpdatedVersion = maxSpeedNewValueMetadata.getLastUpdatedVersion(); //Shall contain `4`
 
 
```
See Also:

Understand and use device twins in IoT Hub, Device Twin Api, Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from class java.util.AbstractMap
  AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
- Nested classes/interfaces inherited from interface java.util.Map
  Map.Entry<K,V>

Constructor Summary

Constructors
Constructor and Description
`TwinCollection()` Constructor
`TwinCollection(Map<? extends String,Object> map)` Constructor
`TwinCollection(TwinCollection collection)` Constructor

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected static TwinCollection`	`createFromRawCollection(Map<? extends String,Object> rawCollection)` Internal Constructor from raw map.
`TwinMetadata`	`getTwinMetadata()` Deprecated. as of Deps version 0.7.1, please use `getTwinMetadataFinal()`
`TwinMetadata`	`getTwinMetadata(String key)` Deprecated. as of Deps version 0.7.1, please use `getTwinMetadataFinal(String)`
`TwinMetadata`	`getTwinMetadataFinal()` Getter for the TwinCollection metadata
`TwinMetadata`	`getTwinMetadataFinal(String key)` Getter for the entry metadata in the TwinCollection.
`Integer`	`getVersion()` Deprecated. as of Deps version 0.7.1, please use `getVersionFinal()`
`Integer`	`getVersionFinal()` Getter for the version.
`Object`	`put(String key, Object value)` Deprecated. as of Deps version 0.7.1, please use `putFinal(String, Object)`
`void`	`putAll(Map<? extends String,?> map)` Deprecated. as of Deps version 0.7.1, please use `putAllFinal(Map)`
`void`	`putAllFinal(Map<? extends String,?> map)` Add all information in the provided Map to the TwinCollection.
`Object`	`putFinal(String key, Object value)` Add a single new entry in the TwinCollection.
`com.google.gson.JsonElement`	`toJsonElement()` Serializer
`protected com.google.gson.JsonElement`	`toJsonElementWithMetadata()` Serializer with metadata.
`String`	`toString()` Creates a pretty print JSON with the content of this class and subclasses.

Methods inherited from class java.util.HashMap
clear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.util.AbstractMap
equals, hashCode

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map
equals, hashCode

- Constructor Detail
  - TwinCollection
```
public TwinCollection()
```
    Constructor
    Creates an empty collection. Fill it with putFinal(String, Object) or putAllFinal(Map).
  - TwinCollection
```
public TwinCollection(Map<? extends String,Object> map)
```
    Constructor
    Creates a new Twin collection coping the provided Map.
    
    Parameters:
    
    map - the Map of ? extends String and Object with the Twin collection
  - TwinCollection
```
public TwinCollection(TwinCollection collection)
```
    Constructor
    Creates a new Twin collection coping the provided collection.
    
    Parameters:
    
    collection - the Collection of ? extends String and Object with the Twin collection
- Method Detail
  - putAll
```
@Deprecated
public void putAll(Map<? extends String,?> map)
```
    Deprecated. as of Deps version 0.7.1, please use putAllFinal(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.
    
    Specified by:
    
    putAll in interface Map<String,Object>
    
    Overrides:
    
    putAll in class HashMap<String,Object>
    
    Parameters:
    
    map - A Map of entries to add to the TwinCollection.
  - putAllFinal
```
public final void putAllFinal(Map<? extends String,?> map)
```
    Add all information in the provided Map to the TwinCollection.
    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.
    
    Parameters:
    
    map - A Map of entries to add to the TwinCollection.
  - put
```
@Deprecated
public Object put(String key,
                               Object value)
```
    Deprecated. as of Deps version 0.7.1, please use putFinal(String, Object)
    
    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.
    
    Specified by:
    
    put in interface Map<String,Object>
    
    Overrides:
    
    put in class HashMap<String,Object>
    
    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.
  - putFinal
```
public final Object putFinal(String key,
                             Object value)
```
    Add a single new entry in the TwinCollection.
    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.
    
    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.
  - createFromRawCollection
```
protected static TwinCollection createFromRawCollection(Map<? extends String,Object> rawCollection)
```
    Internal Constructor from raw map.
    This internal constructor is used to the deserialization process.
    During the deserialization process, the GSON will convert both tags and properties to a raw Map, which will includes the $version and $metadata as part of the collection. So, we need to reorganize this map using the TwinCollection format. This constructor will do that.
    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
 }
 
 
```
    Parameters:
    
    rawCollection - the Map<? extends String, Object> with contain all TwinCollection information, without any differentiation between each entity is the Twin information and each entity is part of the Twin metadata.
    
    Returns:
    
    The instance of the TwinCollection.
    
    Throws:
    
    IllegalArgumentException - If the provided rowCollection contain an invalid parameter.
  - toJsonElement
```
public com.google.gson.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.
  - toJsonElementWithMetadata
```
protected com.google.gson.JsonElement toJsonElementWithMetadata()
```
    Serializer with metadata.
    Return a JsonElement with the full content of this class, including the metadata.
    
    Returns:
    
    The JsonElement with the full content of this class.
  - getVersion
```
@Deprecated
public Integer getVersion()
```
    Deprecated. as of Deps version 0.7.1, please use getVersionFinal()
    
    Getter for the version.
    
    Returns:
    
    The Integer with the version content. It can be null.
  - getVersionFinal
```
public final Integer getVersionFinal()
```
    Getter for the version.
    
    Returns:
    
    The Integer with the version content. It can be null.
  - getTwinMetadata
```
@Deprecated
public TwinMetadata getTwinMetadata()
```
    Deprecated. as of Deps version 0.7.1, please use getTwinMetadataFinal()
    
    Getter for the TwinCollection metadata
    
    Returns:
    
    the TwinMetadata of the Whole TwinCollection. It can be null.
  - getTwinMetadataFinal
```
public final TwinMetadata getTwinMetadataFinal()
```
    Getter for the TwinCollection metadata
    
    Returns:
    
    the TwinMetadata of the Whole TwinCollection. It can be null.
  - getTwinMetadata
```
@Deprecated
public TwinMetadata getTwinMetadata(String key)
```
    Deprecated. as of Deps version 0.7.1, please use getTwinMetadataFinal(String)
    
    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.
  - getTwinMetadataFinal
```
public final TwinMetadata getTwinMetadataFinal(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.
  - toString
```
public String toString()
```
    Creates a pretty print JSON with the content of this class and subclasses.
    
    Overrides:
    
    toString in class AbstractMap<String,Object>
    
    Returns:
    
    The String with the pretty print JSON.

Class TwinCollection

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

Nested classes/interfaces inherited from interface java.util.Map

Constructor Summary

Method Summary

Methods inherited from class java.util.HashMap

Methods inherited from class java.util.AbstractMap

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Constructor Detail

TwinCollection

TwinCollection

TwinCollection

Method Detail

putAll

putAllFinal

put

putFinal

createFromRawCollection

toJsonElement

toJsonElementWithMetadata

getVersion

getVersionFinal

getTwinMetadata

getTwinMetadataFinal

getTwinMetadata

getTwinMetadataFinal

toString