com.microsoft.azure.sdk.iot.device.twin

Classes

DeviceTwin
DirectMethod
DirectMethodPayload

This class contains the payload of a direct method request that was received by the device/module. It is used with the onMethodInvoked() callback which is executed each time a direct method is invoked.

DirectMethodResponse
MethodParser

Representation of a single Direct Method Access collection with a Json serializer and deserializer.

Pair<Type1,Type2>
ParserUtility

Set of static functions to help the serializer.

Property
ReportedPropertiesUpdateResponse

The response fields for a reported properties update request.

Twin

Representation of a single Twin.

The Twin can contain one TwinCollection of Tags, and one TwinCollection of properties.desired.

Each entity in the collections can contain a associated TwinMetadata.

These metadata are provided by the Service and contains information about the last updated date time, and version.

For instance, the following is a valid Twin, represented as initialTwin 

</code> in the rest API. <pre><code>{

    "initialTwin": {

        "tags":{

            "SpeedUnity":"MPH",

            "$metadata":{

                "$lastUpdated":"2017-09-21T02:07:44.238Z",

                "$lastUpdatedVersion":4,

                "SpeedUnity":{

                    "$lastUpdated":"2017-09-21T02:07:44.238Z",

                    "$lastUpdatedVersion":4

                }

            },

            "$version":4

        },

        "properties":{

            "desired": {

                "MaxSpeed":{

                    "Value":500,

                    "NewValue":300

                },

                "$metadata":{

                    "$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

            },

            "reported": {

                "MaxSpeed":{

                    "Value":500,

                    "NewValue":300

                },

                "$metadata":{

                    "$lastUpdated":"2017-09-21T02:07:44.238Z",

                    "$lastUpdatedVersion":5,

                    "MaxSpeed":{

                        "$lastUpdated":"2017-09-21T02:07:44.238Z",

                        "$lastUpdatedVersion":4,

                        "Value":{

                            "$lastUpdated":"2017-09-21T02:07:44.238Z",

                            "$lastUpdatedVersion":5

                        },

                        "NewValue":{

                            "$lastUpdated":"2017-09-21T02:07:44.238Z",

                            "$lastUpdatedVersion":4

                        }

                    }

                },

                "$version":6

            }

        }

    }

}

</code></pre></p>

TwinCollection

Representation of a single Twin collection.

The TwinCollection is an extension of aHashMap  ofString  and Object  that contain individual and general versioning mechanism.

By the Twin definition, theObject  can contain types ofBoolean  , 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 theHashMap  , 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 get 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 theDate  for example 2017-09-21T02:07:44.238Z, getLastUpdatedBy() that will return theString  for example testConfig, getLastUpdatedByDigest() that will return theString  for example 637570515479675333, and getLastUpdatedVersion() that will return theInteger  for example 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`
    

TwinMetadata

Representation of a single Twin metadata for the TwinCollection.

The metadata is a set of pairs lastUpdated/lastUpdatedVersion for each property and sub-property in the Twin. It is optionally provided by the service and the clients can only ready it.

This class store the Date and Version for each entity in the TwinCollection.

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

"$metadata":{
    "$lastUpdated":"2017-09-21T02:07:44.238Z",

    "$lastUpdatedVersion":4,

    "MaxSpeed":{

        "$lastUpdated":"2017-09-21T02:07:44.238Z",

        "$lastUpdatedVersion":3,

        "$lastUpdatedBy": "newconfig",

        "$lastUpdatedByDigest": "637570574076206429",

        "Value":{

            "$lastUpdated":"2017-09-21T02:07:44.238Z",

            "$lastUpdatedVersion":5

        },

        "NewValue":{

            "$lastUpdated":"2017-09-21T02:07:44.238Z",

            "$lastUpdatedVersion":5

        }

    }

}

</code></pre></p>

TwinProperties

Representation of a single Twin Properties for the Twin.

The Properties on the Twin shall contains one TwinCollection of desired property.

The desired property is a collection that can contain a associated TwinMetadata.

These metadata are provided by the Service and contains information about the last updated date time, and version.

For instance, the following is a valid desired property, represented as properties.desired 

</code> in the rest API. <pre><code>{

    "desired": {

        "MaxSpeed":{

            "Value":500,

            "NewValue":300

        },

        "$metadata":{

            "$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

    },

    "reported": {

        "MaxSpeed":{

            "Value":500,

            "NewValue":300

        },

        "$metadata":{

            "$lastUpdated":"2017-09-21T02:07:44.238Z",

            "$lastUpdatedVersion":5,

            "MaxSpeed":{

                "$lastUpdated":"2017-09-21T02:07:44.238Z",

                "$lastUpdatedVersion":4,

                "Value":{

                    "$lastUpdated":"2017-09-21T02:07:44.238Z",

                    "$lastUpdatedVersion":5

                },

                "NewValue":{

                    "$lastUpdated":"2017-09-21T02:07:44.238Z",

                    "$lastUpdatedVersion":4

                }

            }

        },

        "$version":6

    }

}

</code></pre></p>

Interfaces

DesiredPropertiesCallback

The callback to be executed each time the client receives a desired property update from the service.

GetTwinCallback

The callback to be executed when the service responds to a getTwin request with the current twin.

GetTwinCorrelatingMessageCallback

Detailed state notification callback for tracking a particular getTwinAsync(GetTwinCorrelatingMessageCallback twinCallback, Object callbackContext) request.

Users who don't need all this information are advised to use getTwinAsync(GetTwinCallback twinCallback, Object callbackContext) instead.

MethodCallback

The callback to be executed each time a direct method is invoked on this client.

ReportedPropertiesCallback

Callback to be executed when a reported properties update request has completed.

ReportedPropertiesUpdateCorrelatingMessageCallback
SubscriptionAcknowledgedCallback

Callback to be executed when the request to subscribe to desired properties has been acknowledged by the service.

Enums

DeviceOperations
MethodParser.Operation