EnrollmentGroup (Provisioning Service Client 1.7.1 API)

java.lang.Object
- com.microsoft.azure.sdk.iot.provisioning.service.configs.Serializable
- - com.microsoft.azure.sdk.iot.provisioning.service.configs.EnrollmentGroup

All Implemented Interfaces:: Serializable

public class EnrollmentGroup
extends Serializable

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

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

To create or update an EnrollmentGroup on the provisioning service you should fill this object and call the public API ProvisioningServiceClient.createOrUpdateEnrollmentGroup(EnrollmentGroup). The minimum information required by the provisioning service is the enrollmentGroupId and the attestation.

To provision a device using EnrollmentGroup, it must contain a X509 chip with a signingCertificate for the X509Attestation mechanism, or use SymmetricKeyAttestation mechanism.

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 EnrollmentGroup will look like the following example:

 
 {
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]"
             }
         }
     },
     "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 EnrollmentGroup operation like create, update, or query EnrollmentGroup.

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

 
 {
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]",
                 "info": {
                     "subjectName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "sha1Thumbprint": "0000000000000000000000000000000000",
                     "sha256Thumbprint": "validEnrollmentGroupId",
                     "issuerName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "notBeforeUtc": "2017-11-14T12:34:18Z",
                     "notAfterUtc": "2017-11-20T12:34:18Z",
                     "serialNumber": "000000000000000000",
                     "version": 3
                 }
             }
         }
     },
     "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\""
 }

See Also:: Device Enrollment Group, Serialized Form

Constructor Summary

Constructors
Constructor and Description

EnrollmentGroup(String json)
CONSTRUCTOR

EnrollmentGroup(String enrollmentGroupId, Attestation attestation)
CONSTRUCTOR

Constructors
Constructor and Description
`EnrollmentGroup(String json)` CONSTRUCTOR
`EnrollmentGroup(String enrollmentGroupId, Attestation attestation)` CONSTRUCTOR

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`AllocationPolicy`	`getAllocationPolicy()` Getter for the allocation policy.
`Attestation`	`getAttestation()` Getter for the attestation mechanism.
`com.microsoft.azure.sdk.iot.deps.twin.DeviceCapabilities`	`getCapabilities()`
`Date`	`getCreatedDateTimeUtc()` Getter for the createdDateTimeUtcDate.
`CustomAllocationDefinition`	`getCustomAllocationDefinition()` Getter for the custom allocation definition policy.
`String`	`getEnrollmentGroupId()` Getter for the enrollmentGroupId.
`String`	`getEtag()` Getter for the etag.
`TwinState`	`getInitialTwin()` Getter for the initialTwin.
`String`	`getIotHubHostName()` Getter for the iotHubHostName.
`Collection<String>`	`getIotHubs()` Getter for the list of IoTHub names that the device can be allocated to..
`Date`	`getLastUpdatedDateTimeUtc()` Getter for the lastUpdatedDateTimeUtcDate.
`ProvisioningStatus`	`getProvisioningStatus()` Getter for the provisioningStatus.
`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 void`	`setAttestation(AttestationMechanism attestationMechanism)` Setter for the attestation.
`void`	`setCapabilities(com.microsoft.azure.sdk.iot.deps.twin.DeviceCapabilities capabilities)`
`protected void`	`setCreatedDateTimeUtc(String createdDateTimeUtc)` Setter for the createdDateTimeUtc.
`void`	`setCustomAllocationDefinition(CustomAllocationDefinition customAllocationDefinition)` Setter for the custom allocation definition policy.
`protected void`	`setEnrollmentGroupId(String enrollmentGroupId)` Setter for the enrollmentGroupId.
`void`	`setEtag(String etag)` Deprecated. as of provisioning-service-client version 1.3.3, please use `setEtagFinal(String)`
`void`	`setEtagFinal(String etag)` Setter for the etag.
`void`	`setInitialTwin(TwinState initialTwin)` Deprecated.
`void`	`setInitialTwinFinal(TwinState initialTwin)` Setter for the initialTwin.
`void`	`setIotHubHostName(String iotHubHostName)` Deprecated.
`void`	`setIotHubHostNameFinal(String iotHubHostName)` Setter for the iotHubHostName.
`void`	`setIotHubs(Collection<String> iotHubs)` Setter for the list of IotHubs available for allocation.
`protected 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)`
`void`	`setProvisioningStatusFinal(ProvisioningStatus provisioningStatus)` Setter for the provisioningStatus.
`void`	`setReprovisionPolicy(ReprovisionPolicy reprovisionPolicy)` Setter for the reprovision policy.
`com.google.gson.JsonElement`	`toJsonElement()` Serializer

Methods inherited from class com.microsoft.azure.sdk.iot.provisioning.service.configs.Serializable
toJson, toString

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

- Constructor Detail
  - EnrollmentGroup
```
public EnrollmentGroup(String enrollmentGroupId,
                       Attestation attestation)
```
    CONSTRUCTOR
    This constructor creates an instance of the enrollment group with the minimum set of information required by the provisioning service.
    When serialized, an EnrollmentGroup will look like the following example:
```
 
 {
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]"
             }
         }
     }
 }
 
 
```
    Parameters:
    
    enrollmentGroupId - the String with an unique id for this enrollment group.
    
    attestation - the Attestation mechanism that shall be signedCertificate of X509Attestation or symmetricKey of SymmetricKeyAttestation
    
    Throws:
    
    IllegalArgumentException - If one of the provided parameters is not correct.
  - EnrollmentGroup
```
public EnrollmentGroup(String json)
```
    CONSTRUCTOR
    This constructor creates an instance of the enrollment group filling the class with the information provided in the JSON.
    The following JSON is a sample of the EnrollmentGroup response, received from the provisioning service.
```
 
 {
     "enrollmentGroupId":"validEnrollmentGroupId",
     "attestation":{
         "type":"x509",
         "signingCertificates":{
             "primary":{
                 "certificate":"[valid certificate]",
                 "info": {
                     "subjectName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "sha1Thumbprint": "0000000000000000000000000000000000",
                     "sha256Thumbprint": "validEnrollmentGroupId",
                     "issuerName": "CN=ROOT_00000000-0000-0000-0000-000000000000, OU=Azure IoT, O=MSFT, C=US",
                     "notBeforeUtc": "2017-11-14T12:34:18Z",
                     "notAfterUtc": "2017-11-20T12:34:18Z",
                     "serialNumber": "000000000000000000",
                     "version": 3
                 }
             }
         }
     },
     "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.
    
    Throws:
    
    IllegalArgumentException - If the provided JSON is null, empty, or invalid.
- Method Detail
  - 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 jsons from other classes to generate a consolidated JSON.
    
    Specified by:
    
    toJsonElement in class Serializable
    
    Returns:
    
    The JsonElement with the content of this class.
  - getEnrollmentGroupId
```
public String getEnrollmentGroupId()
```
    Getter for the enrollmentGroupId.
    
    Returns:
    
    The String with the enrollmentGroupId content. It cannot be null or empty.
  - setEnrollmentGroupId
```
protected final void setEnrollmentGroupId(String enrollmentGroupId)
```
    Setter for the enrollmentGroupId.
    A valid enrollment group Id shall follow this criteria. A case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
    
    Parameters:
    
    enrollmentGroupId - the String with the new enrollmentGroupId. It cannot be null, empty, or invalid.
    
    Throws:
    
    IllegalArgumentException - If the provided enrollmentGroupId is null, empty, or invalid.
  - getAttestation
```
public Attestation getAttestation()
                           throws ProvisioningServiceClientException
```
    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.
  - setAttestation
```
protected final void setAttestation(AttestationMechanism attestationMechanism)
```
    Setter for the attestation.
    Attestation mechanism is 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'.
    
    Throws:
    
    IllegalArgumentException - If the provided attestation mechanism is null.
    
    See Also:
  - setAttestation
```
public void setAttestation(Attestation attestation)
```
    Setter for the attestation.
    Attestation mechanism is mandatory parameter that provides the mechanism type and the necessary certificates.
    EnrollmentGroup only accept X509Attestation with the RootCertificates, or SymmetricKeyAttestation with Primary and Secondary Keys. You can create an X509Attestation by providing the .pem content to X509Attestation.createFromRootCertificates(String, String). You can create a SymmetricKeyAttestation by providing the Primary and Secondary Keys in Base64 format.
    
    Parameters:
    
    attestation - the Attestation with the new attestation mechanism. It shall be X509Attestation or SymmetricKeyAttestation
    
    Throws:
    
    IllegalArgumentException - If the provided attestation mechanism is null or invalid.
    
    See Also:
    
    Attestation, X509Attestation, SymmetricKeyAttestation
  - getIotHubHostName
```
public String getIotHubHostName()
```
    Getter for the iotHubHostName.
    
    Returns:
    
    The String with the iotHubHostName content. It cannot be null or empty.
  - setIotHubHostName
```
@Deprecated
public void setIotHubHostName(String iotHubHostName)
```
    Deprecated.
    
    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.
    
    Throws:
    
    IllegalArgumentException - If the provided iotHubHostName is 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.
    
    Throws:
    
    IllegalArgumentException - If the provided iotHubHostName is null, empty, or invalid.
  - getInitialTwin
```
public TwinState getInitialTwin()
```
    Getter for the initialTwin.
    
    Returns:
    
    The TwinState with the initialTwin content. Its optional and can be null.
  - setInitialTwin
```
@Deprecated
public void setInitialTwin(TwinState initialTwin)
```
    Deprecated.
    
    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.
    
    Throws:
    
    IllegalArgumentException - If the provided initialTwin is null.
  - setInitialTwinFinal
```
public final void setInitialTwinFinal(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.
    
    Throws:
    
    IllegalArgumentException - If the provided initialTwin is null.
  - getProvisioningStatus
```
public ProvisioningStatus getProvisioningStatus()
```
    Getter for the provisioningStatus.
    
    Returns:
    
    The ProvisioningStatus with the provisioningStatus content. It can be 'enabled' or 'disabled'.
  - setProvisioningStatus
```
@Deprecated
public void setProvisioningStatus(ProvisioningStatus provisioningStatus)
```
    Deprecated. as of provisioning-service-client version 1.3.3, please use setProvisioningStatusFinal(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.
    
    Throws:
    
    IllegalArgumentException - If the provided provisioningStatus is 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.
    
    Throws:
    
    IllegalArgumentException - If the provided provisioningStatus is null.
  - getCreatedDateTimeUtc
```
public Date getCreatedDateTimeUtc()
```
    Getter for the createdDateTimeUtcDate.
    
    Returns:
    
    The Date with the createdDateTimeUtcDate content. It can be null.
  - setCreatedDateTimeUtc
```
protected final void setCreatedDateTimeUtc(String createdDateTimeUtc)
```
    Setter for the createdDateTimeUtc.
    This Date and Time is provided by the provisioning service. If the enrollmentGroup 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.
  - getLastUpdatedDateTimeUtc
```
public Date getLastUpdatedDateTimeUtc()
```
    Getter for the lastUpdatedDateTimeUtcDate.
    
    Returns:
    
    The Date with the lastUpdatedDateTimeUtcDate content. It can be null.
  - setLastUpdatedDateTimeUtc
```
protected final void setLastUpdatedDateTimeUtc(String lastUpdatedDateTimeUtc)
```
    Setter for the lastUpdatedDateTimeUtc.
    This Date and Time is provided by the provisioning service. If the enrollmentGroup 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.
  - getEtag
```
public String getEtag()
```
    Getter for the etag.
    
    Returns:
    
    The String with the etag content. It can be null.
  - setEtag
```
@Deprecated
public void setEtag(String etag)
```
    Deprecated. as of provisioning-service-client version 1.3.3, please use setEtagFinal(String)
    
    Setter for the etag.
    
    Parameters:
    
    etag - the String with the new etag. It cannot be null, empty or invalid.
    
    Throws:
    
    IllegalArgumentException - If the provided etag is 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.
    
    Throws:
    
    IllegalArgumentException - If the provided etag is null, empty or invalid.
  - getCapabilities
```
public com.microsoft.azure.sdk.iot.deps.twin.DeviceCapabilities getCapabilities()
```
  - setCapabilities
```
public final void setCapabilities(com.microsoft.azure.sdk.iot.deps.twin.DeviceCapabilities capabilities)
```
    Parameters:
    
    capabilities - the device capabilities to set
  - getReprovisionPolicy
```
public ReprovisionPolicy getReprovisionPolicy()
```
    Getter for the reprovision policy.
    
    Returns:
    
    The ReprovisionPolicy with the reprovisionPolicy content.
  - 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.
  - getAllocationPolicy
```
public AllocationPolicy getAllocationPolicy()
```
    Getter for the allocation policy.
    
    Returns:
    
    The AllocationPolicy with the allocationPolicy 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.
  - getIotHubs
```
public Collection<String> getIotHubs()
```
    Getter for the list of IoTHub names that the device can be allocated to..
    
    Returns:
    
    The AllocationPolicy with the allocationPolicy content.
  - setIotHubs
```
public void setIotHubs(Collection<String> iotHubs)
```
    Setter for the list of IotHubs available for allocation.
    
    Parameters:
    
    iotHubs - the List<String> 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
  - getCustomAllocationDefinition
```
public CustomAllocationDefinition getCustomAllocationDefinition()
```
    Getter for the custom allocation definition policy.
    
    Returns:
    
    The CustomAllocationDefinition policy.
  - 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.

Class EnrollmentGroup

Constructor Summary

Method Summary

Methods inherited from class com.microsoft.azure.sdk.iot.provisioning.service.configs.Serializable

Methods inherited from class java.lang.Object

Constructor Detail

EnrollmentGroup

EnrollmentGroup

Method Detail

toJsonElement

getEnrollmentGroupId

setEnrollmentGroupId

getAttestation

setAttestation

setAttestation

getIotHubHostName

setIotHubHostName

setIotHubHostNameFinal

getInitialTwin

setInitialTwin

setInitialTwinFinal

getProvisioningStatus

setProvisioningStatus

setProvisioningStatusFinal

getCreatedDateTimeUtc

setCreatedDateTimeUtc

getLastUpdatedDateTimeUtc

setLastUpdatedDateTimeUtc

getEtag

setEtag

setEtagFinal

getCapabilities

setCapabilities

getReprovisionPolicy

setReprovisionPolicy

getAllocationPolicy

setAllocationPolicy

getIotHubs

setIotHubs

getCustomAllocationDefinition

setCustomAllocationDefinition