|
ProvisioningServiceClient
|
Device Provisioning Service Client.
The IoT Hub Device Provisioning Service is a helper service for IoT Hub that enables automatic device provisioning to a specified IoT hub without requiring human intervention. You can use the Device Provisioning Service to provision millions of devices in a secure and scalable manner.
This java SDK provides an API to help developers to create and maintain Enrollments on the IoT Hub Device Provisioning Service, it translate the rest API in java Objects and Methods.
To use the this SDK, you must include the follow package on your application. // Include the following imports to use the Device Provisioning Service APIs.
import com.microsoft.azure.sdk.iot.provisioning.service.*;
</code></pre></p>
The main APIs are exposed by the ProvisioningServiceClient, it contains the public Methods that the application shall call to create and maintain the Enrollments. The Objects in the configs package shall be filled and passed as parameters of the public API, for example, to create a new enrollment, the application shall create the object IndividualEnrollment with the appropriate enrollment configurations, and call the createOrUpdateIndividualEnrollment(IndividualEnrollment individualEnrollment).
The IoT Hub Device Provisioning Service supports SQL queries too. The application can create a new query using one of the queries factories, for instance createIndividualEnrollmentQuery(QuerySpecification querySpecification), passing the QuerySpecification, with the SQL query. This factory returns a Query object, which is an active iterator.
This java SDK can be represented in the follow diagram, the first layer are the public APIs the your application shall use:
+===============+ +==========================================+ +============+ +===+
| configs |------>| ProvisioningServiceClient | +->| Query | | |
+===============+ +==+=================+==================+==+ | +======+=====+ | e |
/ | \ | | | x |
/ | \ | | | c |
+-----------------------+-----+ +-----------+------------+ +-----+---------------------+ | | | e |
| IndividualEnrollmentManager | | EnrollmentGroupManager | | RegistrationStatusManager | | | | p |
+---------------+------+------+ +-----------+------+-----+ +-------------+-------+-----+ | | | t |
\ \ | \ | \ | | | i |
\ +----------------------------+------------------------------+------+ | | o |
\ | | | | n |
+--------+ +--+------------------------+-----------------------------+--------------------------+-----+ | s |
| auth |----->| ContractApiHttp | | |
+--------+ +-------------------------------------------+----------------------------------------------+ +===+
|
|
+-------------------------------------+------------------------------------------+
| com.microsoft.azure.sdk.iot.deps.transport.http |
+--------------------------------------------------------------------------------+
|
|
Query
|
The query iterator.
TheQuery
</code> iterator is the result of the query factory for <table rows="3" cols="2"><caption>Query factories</caption><row><entry thead="no"><p><b>IndividualEnrollment:</b></p></entry><entry thead="no"><p><xref uid="com.microsoft.azure.sdk.iot.provisioning.service.ProvisioningServiceClient.createIndividualEnrollmentQuery(QuerySpecification,int)" data-throw-if-not-resolved="false" data-raw-source="ProvisioningServiceClient#createIndividualEnrollmentQuery(QuerySpecification, int)"></xref></p></entry></row><row><entry thead="no"><p><b>EnrollmentGroup:</b></p></entry><entry thead="no"><p><xref uid="com.microsoft.azure.sdk.iot.provisioning.service.ProvisioningServiceClient.createEnrollmentGroupQuery(QuerySpecification,int)" data-throw-if-not-resolved="false" data-raw-source="ProvisioningServiceClient#createEnrollmentGroupQuery(QuerySpecification, int)"></xref></p></entry></row><row><entry thead="no"><p><b>RegistrationStatus:</b></p></entry><entry thead="no"><p><xref uid="com.microsoft.azure.sdk.iot.provisioning.service.ProvisioningServiceClient.createEnrollmentGroupRegistrationStateQuery(QuerySpecification,String,int)" data-throw-if-not-resolved="false" data-raw-source="ProvisioningServiceClient#createEnrollmentGroupRegistrationStateQuery(QuerySpecification, String, int)"></xref></p></entry></row></table></p>
On all cases, the QuerySpecification contains a SQL query that must follow the Query Language for the Device Provisioning Service.
Optionally, anInteger
</code> with the <b>pageSize</b>, can determine the maximum number of the items in the <xref uid="" data-throw-if-not-resolved="false" data-raw-source="QueryResult"></xref> returned by the <xref uid="com.microsoft.azure.sdk.iot.provisioning.service.Query.next()" data-throw-if-not-resolved="false" data-raw-source="next()"></xref>. It must be any positive integer, and if it contains 0, the Device Provisioning Service will ignore it and use a standard page size.</p>
You can use this Object as a standard Iterator, just using the hasNext() and next() in a while
</code> loop, up to the point where the <xref uid="com.microsoft.azure.sdk.iot.provisioning.service.Query.hasNext()" data-throw-if-not-resolved="false" data-raw-source="hasNext()"></xref> return<code>false
</code> . But, keep in mind that the <xref uid="" data-throw-if-not-resolved="false" data-raw-source="QueryResult"></xref> can contain a empty list, even if the <xref uid="com.microsoft.azure.sdk.iot.provisioning.service.Query.hasNext()" data-throw-if-not-resolved="false" data-raw-source="hasNext()"></xref> returned<code>true
</code> . For example, image that you have 10 IndividualEnrollment in the Device Provisioning Service and you created new query with the<code>pageSize
</code> equals 5. The first<code>hasNext()
</code> will return<code>true
</code> , and the first<code>next()
</code> will return a<code>QueryResult
</code> with 5 items. After that you call the<code>hasNext
</code> , which will returns<code>true
</code> . Now, before you get the next page, somebody delete all the IndividualEnrollment, What happened, when you call the<code>next()
</code> , it will return a valid<code>QueryResult
</code> , but the QueryResult.getItems() will return a empty list.</p>
You can also store a query context (QuerySpecification + ContinuationToken) and restart it in the future, from the point where you stopped.
Besides the Items, the queryResult contains the continuationToken. In any point in the future, you may recreate the query using the same query factories that you used for the first time, and call next(String continuationToken) providing the stored continuationToken to get the next page.
|
