IndividualEnrollment Class

public class IndividualEnrollment
extends Serializable

Representation of a single Device Provisioning Service enrollment with a JSON serializer and deserializer.

This object is used to send IndividualEnrollment information to the provisioning service, or receive IndividualEnrollment information from the provisioning service.

To create or update an IndividualEnrollment on the provisioning service you should fill this object and call the public API createOrUpdateIndividualEnrollment(IndividualEnrollment individualEnrollment). The minimum information required by the provisioning service is the registrationId and the attestation.

A new device can be provisioned by three attestation mechanisms, Trust Platform Module (see TpmAttestation), X509 (see X509Attestation) or SymmetricKeyAttestation mechanism. The definition of each one you should use depending on the physical authentication hardware that the device contains.

The content of this class will be serialized in a JSON format and sent as a body of the rest API to the provisioning service.

When serialized, an IndividualEnrollment will look like the following example:

{
    "registrationId":"validRegistrationId",
    "deviceId":"ContosoDevice-123",
    "attestation":{
        "type":"tpm",
        "tpm":{
            "endorsementKey":"validEndorsementKey"
        }
    },
    "iotHubHostName":"ContosoIoTHub.azure-devices.net",
    "provisioningStatus":"enabled"
 }

The content of this class can be filled by a JSON, received from the provisioning service, as result of a IndividualEnrollment operation like create, update, or query enrollment.

The following JSON is a sample or the IndividualEnrollment response, received from the provisioning service.

{
    "registrationId":"validRegistrationId",
    "deviceId":"ContosoDevice-123",
    "attestation":{
        "type":"tpm",
        "tpm":{
            "endorsementKey":"validEndorsementKey"
        }
    },
    "iotHubHostName":"ContosoIoTHub.azure-devices.net",
    "provisioningStatus":"enabled"
    "createdDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
    "lastUpdatedDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
    "etag": "\"00000000-0000-0000-0000-00000000000\""
 }

Constructor Summary

Constructor Description
IndividualEnrollment(String json)

CONSTRUCTOR

IndividualEnrollment(String registrationId, Attestation attestation)

CONSTRUCTOR

Method Summary

Modifier and Type Method and Description
AllocationPolicy getAllocationPolicy()

Getter for the allocation policy.

Attestation getAttestation()

Getter for the attestation mechanism.

DeviceCapabilities getCapabilities()
java.util.Date getCreatedDateTimeUtc()

Getter for the createdDateTimeUtcDate.

CustomAllocationDefinition getCustomAllocationDefinition()

Getter for the custom allocation definition policy.

java.lang.String getDeviceId()

Getter for the deviceId.

DeviceRegistrationState getDeviceRegistrationState()

Getter for the registrationState.

java.lang.String getEtag()

Getter for the etag.

TwinState getInitialTwin()

Getter for the initialTwin.

java.lang.String getIotHubHostName()

Getter for the iotHubHostName.

java.util.Collection<java.lang.String> getIotHubs()

Getter for the list of IoTHub names that the device can be allocated to..

java.util.Date getLastUpdatedDateTimeUtc()

Getter for the lastUpdatedDateTimeUtcDate.

ProvisioningStatus getProvisioningStatus()

Getter for the provisioningStatus.

java.lang.String getRegistrationId()

Getter for the registrationId.

ReprovisionPolicy getReprovisionPolicy()

Getter for the reprovision policy.

void setAllocationPolicy(AllocationPolicy allocationPolicy)

Setter for the allocation policy.

void setAttestation(Attestation attestation)

Setter for the attestation.

protected final void setAttestation(AttestationMechanism attestationMechanism)

Setter for the attestation.

void setCapabilities(DeviceCapabilities capabilities)

Deprecated

as of provisioning-service-client version 1.3.3, please use setCapabilitiesFinal(DeviceCapabilities capabilities)
final void setCapabilitiesFinal(DeviceCapabilities capabilities)
protected final void setCreatedDateTimeUtc(String createdDateTimeUtc)

Setter for the createdDateTimeUtc.

void setCustomAllocationDefinition(CustomAllocationDefinition customAllocationDefinition)

Setter for the custom allocation definition policy.

void setDeviceId(String deviceId)

Deprecated

as of provisioning-service-client version 1.3.3, please use setDeviceIdFinal(String deviceId)

Setter for the deviceId.

final void setDeviceIdFinal(String deviceId)

Setter for the deviceId.

void setEtag(String etag)

Deprecated

as of provisioning-service-client version 1.3.3, please use setEtagFinal(String etag)

Setter for the etag.

final void setEtagFinal(String etag)

Setter for the etag.

void setInitialTwin(TwinState initialTwin)

Setter for the initialTwin.

void setIotHubHostName(String iotHubHostName)

Deprecated

as of provisioning-service-client version 1.3.3, please use setIotHubHostNameFinal(String iotHubHostName)

Setter for the iotHubHostName.

final void setIotHubHostNameFinal(String iotHubHostName)

Setter for the iotHubHostName.

void setIotHubs(Collection<String> iotHubs)

Setter for the list of IotHubs available for allocation.

protected final void setLastUpdatedDateTimeUtc(String lastUpdatedDateTimeUtc)

Setter for the lastUpdatedDateTimeUtc.

void setProvisioningStatus(ProvisioningStatus provisioningStatus)

Deprecated

as of provisioning-service-client version 1.3.3, please use setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

final void setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

protected final void setRegistrationId(String registrationId)

Setter for the registrationId.

protected final void setRegistrationState(DeviceRegistrationState registrationState)

Setter for the registrationState.

void setReprovisionPolicy(ReprovisionPolicy reprovisionPolicy)

Setter for the reprovision policy.

com.google.gson.JsonElement toJsonElement()

Serializer

Methods inherited from Serializable

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

IndividualEnrollment

public IndividualEnrollment(String json)

CONSTRUCTOR

This constructor creates an instance of the enrollment filling the class with the information provided in the JSON. It is used by the SDK to parse enrollment responses from the provisioning service.

The following JSON is a sample of the IndividualEnrollment response, received from the provisioning service.

{
    "registrationId":"validRegistrationId",
    "deviceId":"ContosoDevice-123",
    "attestation":{
        "type":"tpm",
        "tpm":{
            "endorsementKey":"validEndorsementKey"
        }
    },
    "iotHubHostName":"ContosoIoTHub.azure-devices.net",
    "provisioningStatus":"enabled"
    "createdDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
    "lastUpdatedDateTimeUtc": "2017-09-28T16:29:42.3447817Z",
    "etag": "\"00000000-0000-0000-0000-00000000000\""
 }

Parameters:

json - the String with the JSON received from the provisioning service.

IndividualEnrollment

public IndividualEnrollment(String registrationId, Attestation attestation)

CONSTRUCTOR

This constructor creates an instance of the enrollment with the minimum set of information required by the provisioning service. A valid enrollment must contain the registrationId, which uniquely identify this enrollment, and the attestation mechanism, which can be TPM, X509 or SymmetricKey.

Other parameters can be added by calling the setters on this class.

When serialized, an IndividualEnrollment will look like the following example:

{
    "registrationId":"validRegistrationId",
    "attestation":{
        "type":"tpm",
        "tpm":{
            "endorsementKey":"validEndorsementKey"
        }
    }
 }

Parameters:

registrationId - the String with an unique id for this enrollment.
attestation - the Attestation mechanism that can be TpmAttestation, X509Attestation or SymmetricKeyAttestation.

Method Details

getAllocationPolicy

public AllocationPolicy getAllocationPolicy()

Getter for the allocation policy.

Returns:

The AllocationPolicy with the allocationPolicy content.

getAttestation

public Attestation getAttestation()

Getter for the attestation mechanism.

Returns:

The Attestation with the attestation content. It cannot be null.

Throws:

ProvisioningServiceClientException - If the type of the attestation mechanism is unknown.

getCapabilities

public DeviceCapabilities getCapabilities()

getCreatedDateTimeUtc

public Date getCreatedDateTimeUtc()

Getter for the createdDateTimeUtcDate.

Returns:

The Date with the createdDateTimeUtcDate content. It can be null.

getCustomAllocationDefinition

public CustomAllocationDefinition getCustomAllocationDefinition()

Getter for the custom allocation definition policy.

Returns:

The CustomAllocationDefinition policy.

getDeviceId

public String getDeviceId()

Getter for the deviceId.

Returns:

The String with the deviceID content. It cannot be null or empty.

getDeviceRegistrationState

public DeviceRegistrationState getDeviceRegistrationState()

Getter for the registrationState.

Returns:

The DeviceRegistrationState with the registrationState content. It can be null.

getEtag

public String getEtag()

Getter for the etag.

Returns:

The String with the etag content. It can be null.

getInitialTwin

public TwinState getInitialTwin()

Getter for the initialTwin.

Returns:

The TwinState with the initialTwin content. Its optional and can be null.

getIotHubHostName

public String getIotHubHostName()

Getter for the iotHubHostName.

Returns:

The String with the iotHubHostName content. It cannot be null or empty.

getIotHubs

public Collection getIotHubs()

Getter for the list of IoTHub names that the device can be allocated to..

Returns:

The AllocationPolicy with the allocationPolicy content.

getLastUpdatedDateTimeUtc

public Date getLastUpdatedDateTimeUtc()

Getter for the lastUpdatedDateTimeUtcDate.

Returns:

The Date with the lastUpdatedDateTimeUtcDate content. It can be null.

getProvisioningStatus

public ProvisioningStatus getProvisioningStatus()

Getter for the provisioningStatus.

Returns:

The ProvisioningStatus with the provisioningStatus content. It can be 'enabled' or 'disabled'.

getRegistrationId

public String getRegistrationId()

Getter for the registrationId.

Returns:

The String with the registrationID content. It cannot be null or empty.

getReprovisionPolicy

public ReprovisionPolicy getReprovisionPolicy()

Getter for the reprovision policy.

Returns:

The ReprovisionPolicy with the reprovisionPolicy content.

setAllocationPolicy

public void setAllocationPolicy(AllocationPolicy allocationPolicy)

Setter for the allocation policy.

Parameters:

allocationPolicy - the AllocationPolicy with the allocation policy of this resource. Overrides the tenant level allocation policy.

setAttestation

public void setAttestation(Attestation attestation)

Setter for the attestation.

Attestation mechanism is a mandatory parameter that provides the mechanism type and the necessary keys/certificates

Parameters:

attestation - the Attestation with the new attestation mechanism. It can be TpmAttestation, X509Attestation or SymmetricKeyAttestation.

setAttestation

protected final void setAttestation(AttestationMechanism attestationMechanism)

Setter for the attestation.

Attestation mechanism is a mandatory parameter that provides the mechanism type and the necessary keys/certificates

Parameters:

attestationMechanism - the AttestationMechanism with the new attestation mechanism. It can be tpm, x509 or SymmetricKey.

setCapabilities


public void setCapabilities(DeviceCapabilities capabilities)

Deprecated

as of provisioning-service-client version 1.3.3, please use setCapabilitiesFinal(DeviceCapabilities capabilities)

Parameters:

capabilities - the device capabilities to set

setCapabilitiesFinal

public final void setCapabilitiesFinal(DeviceCapabilities capabilities)

Parameters:

capabilities - the device capabilities to set

setCreatedDateTimeUtc

protected final void setCreatedDateTimeUtc(String createdDateTimeUtc)

Setter for the createdDateTimeUtc.

This Date and Time is provided by the provisioning service. If the enrollment is not created yet, this string can represent an invalid Date. In this case, it will be ignored.

Example of the expected format: "2016-06-01T21:22:43.7996883Z"

Parameters:

createdDateTimeUtc - the String with the new createdDateTimeUtc. It can be null, empty or not valid.

setCustomAllocationDefinition

public void setCustomAllocationDefinition(CustomAllocationDefinition customAllocationDefinition)

Setter for the custom allocation definition policy.

Parameters:

customAllocationDefinition - the CustomAllocationDefinition with the custom allocation policy of this resource.

setDeviceId


public void setDeviceId(String deviceId)

Deprecated

as of provisioning-service-client version 1.3.3, please use setDeviceIdFinal(String deviceId)

Setter for the deviceId.

Parameters:

deviceId - the String with the new deviceID. It cannot be null, empty, or invalid.

setDeviceIdFinal

public final void setDeviceIdFinal(String deviceId)

Setter for the deviceId.

Parameters:

deviceId - the String with the new deviceID. It cannot be null, empty, or invalid.

setEtag


public void setEtag(String etag)

Deprecated

as of provisioning-service-client version 1.3.3, please use setEtagFinal(String etag)

Setter for the etag.

Parameters:

etag - the String with the new etag. It cannot be null, empty or invalid.

setEtagFinal

public final void setEtagFinal(String etag)

Setter for the etag.

Parameters:

etag - the String with the new etag. It cannot be null, empty or invalid.

setInitialTwin

public void setInitialTwin(TwinState initialTwin)

Setter for the initialTwin.

It provides a Twin precondition for the provisioned device.

Parameters:

initialTwin - the TwinState with the new initialTwin. It cannot be null.

setIotHubHostName


public void setIotHubHostName(String iotHubHostName)

Deprecated

as of provisioning-service-client version 1.3.3, please use setIotHubHostNameFinal(String iotHubHostName)

Setter for the iotHubHostName.

A valid iothub host name shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. A valid host name shall have, at least 2 parts separated by '.'.

Parameters:

iotHubHostName - the String with the new iotHubHostName. It cannot be null, empty, or invalid.

setIotHubHostNameFinal

public final void setIotHubHostNameFinal(String iotHubHostName)

Setter for the iotHubHostName.

A valid iothub host name shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. A valid host name shall have, at least 2 parts separated by '.'.

Parameters:

iotHubHostName - the String with the new iotHubHostName. It cannot be null, empty, or invalid.

setIotHubs

public void setIotHubs(Collection iotHubs)

Setter for the list of IotHubs available for allocation.

Parameters:

iotHubs - the List of names of IoT hubs the device(s) in this resource can be allocated to. Must be a subset of tenant level list of IoT hubs

setLastUpdatedDateTimeUtc

protected final void setLastUpdatedDateTimeUtc(String lastUpdatedDateTimeUtc)

Setter for the lastUpdatedDateTimeUtc.

This Date and Time is provided by the provisioning service. If the enrollment is not created yet, this string can represent an invalid Date. In this case, it will be ignored.

Example of the expected format: "2016-06-01T21:22:43.7996883Z"

Parameters:

lastUpdatedDateTimeUtc - the String with the new lastUpdatedDateTimeUtc. It can be null, empty or not valid.

setProvisioningStatus


public void setProvisioningStatus(ProvisioningStatus provisioningStatus)

Deprecated

as of provisioning-service-client version 1.3.3, please use setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

It provides a Status precondition for the provisioned device.

Parameters:

provisioningStatus - the ProvisioningStatus with the new provisioningStatus. It cannot be null.

setProvisioningStatusFinal

public final void setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)

Setter for the provisioningStatus.

It provides a Status precondition for the provisioned device.

Parameters:

provisioningStatus - the ProvisioningStatus with the new provisioningStatus. It cannot be null.

setRegistrationId

protected final void setRegistrationId(String registrationId)

Setter for the registrationId.

A valid registration Id shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

Parameters:

registrationId - the String with the new registrationId. It cannot be null, empty, or invalid.

setRegistrationState

protected final void setRegistrationState(DeviceRegistrationState registrationState)

Setter for the registrationState.

Parameters:

registrationState - the DeviceRegistrationState with the new registrationState. It cannot be null.

setReprovisionPolicy

public void setReprovisionPolicy(ReprovisionPolicy reprovisionPolicy)

Setter for the reprovision policy.

Parameters:

reprovisionPolicy - the ReprovisionPolicy with the behavior when a device is re-provisioned to an IoT hub.

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.

Overrides:

IndividualEnrollment.toJsonElement()

Returns:

The JsonElement with the content of this class.

Applies to