com.microsoft.azure.sdk.iot.service

Class RegistryManager

java.lang.Object

com.microsoft.azure.sdk.iot.service.RegistryManager

public class RegistryManager
extends Object

Use the RegistryManager class to manage the identity registry in IoT Hubs.

Constructor Summary

Constructors

Constructor and Description
RegistryManager()

Method Summary

Modifier and Type	Method and Description
Configuration	addConfiguration(Configuration configuration) Add configuration using the given Configuration object Return with the response configuration object from IotHub
Device	addDevice(Device device) Add device using the given Device object Return with the response device object from IotHub
CompletableFuture<Device>	addDeviceAsync(Device device) Async wrapper for add() operation
Module	addModule(Module module) Add module using the given Module object Return with the response module object from IotHub
void	applyConfigurationContentOnDevice(String deviceId, ConfigurationContent content) Apply the provided configuration content to the provided device
void	close() Gracefully close running threads, and then shutdown the underlying executor service
static RegistryManager	createFromConnectionString(String connectionString) Static constructor to create instance from connection string
JobProperties	exportDevices(String exportBlobContainerUri, Boolean excludeKeys) Create a bulk export job.
CompletableFuture<JobProperties>	exportDevicesAsync(String exportBlobContainerUri, Boolean excludeKeys) Async wrapper for exportDevices() operation
Configuration	getConfiguration(String configurationId) Get configuration by configuration Id from IotHub
List<Configuration>	getConfigurations(Integer maxCount) Get list of Configuration
Device	getDevice(String deviceId) Get device data by device Id from IotHub
CompletableFuture<Device>	getDeviceAsync(String deviceId) Async wrapper for getDevice() operation
String	getDeviceConnectionString(Device device) Return the iothub device connection string for a provided device.
ArrayList<Device>	getDevices(Integer maxCount) Deprecated. as of release 1.12.0. Please use DeviceTwin.queryTwin(String sqlQuery, Integer pageSize) to query for all devices.
CompletableFuture<ArrayList<Device>>	getDevicesAsync(Integer maxCount) Deprecated. as of release 1.12.0. Please use DeviceTwin.queryTwin(String sqlQuery, Integer pageSize) to query for all devices.
JobProperties	getJob(String jobId) Get the properties of an existing job.
CompletableFuture<JobProperties>	getJobAsync(String jobId) Async wrapper for getJob() operation
Module	getModule(String deviceId, String moduleId) Get module data by device Id and module Id from IotHub
List<Module>	getModulesOnDevice(String deviceId) Get modules data by device Id from IotHub
RegistryStatistics	getStatistics() Get device statistics
CompletableFuture<RegistryStatistics>	getStatisticsAsync() Async wrapper for getStatistics() operation
JobProperties	importDevices(String importBlobContainerUri, String outputBlobContainerUri) Create a bulk import job.
CompletableFuture<JobProperties>	importDevicesAsync(String importBlobContainerUri, String outputBlobContainerUri) Async wrapper for importDevices() operation
void	open() Deprecated. as of release 1.13.0 this API is no longer supported and open is done implicitly by the respective APIs Opens this registry manager's executor service after it has been closed.
void	removeConfiguration(Configuration config) Send remove configuration request and verify response
void	removeConfiguration(String configurationId) Send remove configuration request and verify response
void	removeDevice(Device device) Remove device
void	removeDevice(String deviceId) Remove device
CompletableFuture<Boolean>	removeDeviceAsync(String deviceId) Async wrapper for removeDevice() operation
void	removeModule(Module module) Remove module
void	removeModule(String deviceId, String moduleId) Remove module
Configuration	updateConfiguration(Configuration configuration) Update configuration not forced
Configuration	updateConfiguration(Configuration configuration, Boolean forceUpdate) Update configuration with forceUpdate input parameter
Device	updateDevice(Device device) Update device not forced
Device	updateDevice(Device device, Boolean forceUpdate) Update device with forceUpdate input parameter
CompletableFuture<Device>	updateDeviceAsync(Device device) Async wrapper for updateDevice() operation
CompletableFuture<Device>	updateDeviceAsync(Device device, Boolean forceUpdate) Async wrapper for forced updateDevice() operation
Module	updateModule(Module module) Update module not forced
Module	updateModule(Module module, Boolean forceUpdate) Update module with forceUpdate input parameter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RegistryManager

public RegistryManager()

Method Detail

createFromConnectionString

public static RegistryManager createFromConnectionString(String connectionString)
                                                  throws IOException

Static constructor to create instance from connection string

Parameters:

connectionString - The iot hub connection string

Returns:

The instance of RegistryManager

Throws:

IOException - This exception is thrown if the object creation failed

open

@Deprecated
public void open()

Deprecated. as of release 1.13.0 this API is no longer supported and open is done implicitly by the respective APIs Opens this registry manager's executor service after it has been closed.

close

public void close()

Gracefully close running threads, and then shutdown the underlying executor service

addDevice

public Device addDevice(Device device)
                 throws IOException,
                        IotHubException,
                        com.google.gson.JsonSyntaxException

Add device using the given Device object Return with the response device object from IotHub

Parameters:

device - The device object to add

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

addDeviceAsync

public CompletableFuture<Device> addDeviceAsync(Device device)
                                         throws IOException,
                                                IotHubException

Async wrapper for add() operation

Parameters:

device - The device object to add

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

getDevice

public Device getDevice(String deviceId)
                 throws IOException,
                        IotHubException,
                        com.google.gson.JsonSyntaxException

Get device data by device Id from IotHub

Parameters:

deviceId - The id of requested device

Returns:

The device object of requested device

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getDeviceAsync

public CompletableFuture<Device> getDeviceAsync(String deviceId)
                                         throws IOException,
                                                IotHubException

Async wrapper for getDevice() operation

Parameters:

deviceId - The id of requested device

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

getDevices

@Deprecated
public ArrayList<Device> getDevices(Integer maxCount)
                                          throws IOException,
                                                 IotHubException,
                                                 com.google.gson.JsonSyntaxException

Deprecated. as of release 1.12.0. Please use DeviceTwin.queryTwin(String sqlQuery, Integer pageSize) to query for all devices.

Get list of devices

Parameters:

maxCount - The requested count of devices

Returns:

The array of requested device objects

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getDevicesAsync

@Deprecated
public CompletableFuture<ArrayList<Device>> getDevicesAsync(Integer maxCount)
                                                                  throws IOException,
                                                                         IotHubException

Deprecated. as of release 1.12.0. Please use DeviceTwin.queryTwin(String sqlQuery, Integer pageSize) to query for all devices.

Async wrapper for getDevices() operation

Parameters:

maxCount - The requested count of devices

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

getDeviceConnectionString

public String getDeviceConnectionString(Device device)

Return the iothub device connection string for a provided device.

Parameters:

device - The device object to get the connectionString

Returns:

The iothub device connection string

updateDevice

public Device updateDevice(Device device)
                    throws IOException,
                           IotHubException

Update device not forced

Parameters:

device - The device object containing updated data

Returns:

The updated device object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

updateDevice

public Device updateDevice(Device device,
                           Boolean forceUpdate)
                    throws IOException,
                           IotHubException,
                           com.google.gson.JsonSyntaxException

Update device with forceUpdate input parameter

Parameters:

device - The device object containing updated data

forceUpdate - True if the update has to be forced regardless of the device state

Returns:

The updated device object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

updateDeviceAsync

public CompletableFuture<Device> updateDeviceAsync(Device device)
                                            throws IOException,
                                                   IotHubException

Async wrapper for updateDevice() operation

Parameters:

device - The device object containing updated data

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

updateDeviceAsync

public CompletableFuture<Device> updateDeviceAsync(Device device,
                                                   Boolean forceUpdate)
                                            throws IOException,
                                                   IotHubException

Async wrapper for forced updateDevice() operation

Parameters:

device - The device object containing updated data

forceUpdate - True is the update has to be forced regardless if the device state

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

removeDevice

public void removeDevice(String deviceId)
                  throws IOException,
                         IotHubException

Remove device

Parameters:

deviceId - The device name to remove

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

removeDevice

public void removeDevice(Device device)
                  throws IOException,
                         IotHubException,
                         IllegalArgumentException

Remove device

Parameters:

device - The device name to remove

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

IllegalArgumentException - This exception is thrown if the device is null

removeDeviceAsync

public CompletableFuture<Boolean> removeDeviceAsync(String deviceId)
                                             throws IOException,
                                                    IotHubException

Async wrapper for removeDevice() operation

Parameters:

deviceId - The device object to remove

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

getStatistics

public RegistryStatistics getStatistics()
                                 throws IOException,
                                        IotHubException,
                                        com.google.gson.JsonSyntaxException

Get device statistics

Returns:

RegistryStatistics object containing the requested data

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getStatisticsAsync

public CompletableFuture<RegistryStatistics> getStatisticsAsync()
                                                         throws IOException,
                                                                IotHubException

Async wrapper for getStatistics() operation

Returns:

The future object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

exportDevices

public JobProperties exportDevices(String exportBlobContainerUri,
                                   Boolean excludeKeys)
                            throws IllegalArgumentException,
                                   IOException,
                                   IotHubException,
                                   com.google.gson.JsonSyntaxException

Create a bulk export job.

Parameters:

exportBlobContainerUri - URI containing SAS token to a blob container where export data will be placed

excludeKeys - Whether the devices keys should be excluded from the exported data or not

Returns:

A JobProperties object for the newly created bulk export job

Throws:

IllegalArgumentException - This exception is thrown if the exportBlobContainerUri or excludeKeys parameters are null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

exportDevicesAsync

public CompletableFuture<JobProperties> exportDevicesAsync(String exportBlobContainerUri,
                                                           Boolean excludeKeys)
                                                    throws IllegalArgumentException,
                                                           IOException,
                                                           IotHubException,
                                                           com.google.gson.JsonSyntaxException

Async wrapper for exportDevices() operation

Parameters:

excludeKeys - if to exclude keys or not

exportBlobContainerUri - the blob storage container URI to store at.

Returns:

The future object for the requested operation

Throws:

IllegalArgumentException - This exception is thrown if the exportBlobContainerUri or excludeKeys parameters are null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

importDevices

public JobProperties importDevices(String importBlobContainerUri,
                                   String outputBlobContainerUri)
                            throws IllegalArgumentException,
                                   IOException,
                                   IotHubException,
                                   com.google.gson.JsonSyntaxException

Create a bulk import job.

Parameters:

importBlobContainerUri - URI containing SAS token to a blob container that contains registry data to sync

outputBlobContainerUri - URI containing SAS token to a blob container where the result of the bulk import operation will be placed

Returns:

A JobProperties object for the newly created bulk import job

Throws:

IllegalArgumentException - This exception is thrown if the importBlobContainerUri or outputBlobContainerUri parameters are null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

importDevicesAsync

public CompletableFuture<JobProperties> importDevicesAsync(String importBlobContainerUri,
                                                           String outputBlobContainerUri)
                                                    throws IllegalArgumentException,
                                                           IOException,
                                                           IotHubException,
                                                           com.google.gson.JsonSyntaxException

Async wrapper for importDevices() operation

Parameters:

importBlobContainerUri - Uri for importBlobContainer

outputBlobContainerUri - Uri for outputBlobContainer

Returns:

The future object for the requested operation

Throws:

IllegalArgumentException - This exception is thrown if the exportBlobContainerUri or excludeKeys parameters are null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getJob

public JobProperties getJob(String jobId)
                     throws IllegalArgumentException,
                            IOException,
                            IotHubException,
                            com.google.gson.JsonSyntaxException

Get the properties of an existing job.

Parameters:

jobId - The id of the job to be retrieved.

Returns:

A JobProperties object for the requested job id

Throws:

IllegalArgumentException - This exception is thrown if the jobId parameter is null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getJobAsync

public CompletableFuture<JobProperties> getJobAsync(String jobId)
                                             throws IllegalArgumentException,
                                                    IOException,
                                                    IotHubException

Async wrapper for getJob() operation

Parameters:

jobId - jobID as String

Returns:

The future object for the requested operation

Throws:

IllegalArgumentException - This exception is thrown if the jobId parameter is null

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

addModule

public Module addModule(Module module)
                 throws IOException,
                        IotHubException,
                        com.google.gson.JsonSyntaxException

Add module using the given Module object Return with the response module object from IotHub

Parameters:

module - The module object to add

Returns:

The module object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getModule

public Module getModule(String deviceId,
                        String moduleId)
                 throws IOException,
                        IotHubException,
                        com.google.gson.JsonSyntaxException

Get module data by device Id and module Id from IotHub

Parameters:

deviceId - The id of requested device

moduleId - The id of requested module

Returns:

The module object of requested module on the specific device

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getModulesOnDevice

public List<Module> getModulesOnDevice(String deviceId)
                                throws IOException,
                                       IotHubException,
                                       com.google.gson.JsonSyntaxException

Get modules data by device Id from IotHub

Parameters:

deviceId - The id of requested device

Returns:

The module objects on the specific device

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

updateModule

public Module updateModule(Module module)
                    throws IOException,
                           IotHubException

Update module not forced

Parameters:

module - The module object containing updated data

Returns:

The updated module object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

updateModule

public Module updateModule(Module module,
                           Boolean forceUpdate)
                    throws IOException,
                           IotHubException,
                           com.google.gson.JsonSyntaxException

Update module with forceUpdate input parameter

Parameters:

module - The module object containing updated data

forceUpdate - True if the update has to be forced regardless of the module state

Returns:

The updated module object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

removeModule

public void removeModule(String deviceId,
                         String moduleId)
                  throws IOException,
                         IotHubException

Remove module

Parameters:

deviceId - The device name associated with the module to be removed

moduleId - The module name to be removed

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

removeModule

public void removeModule(Module module)
                  throws IOException,
                         IotHubException,
                         IllegalArgumentException

Remove module

Parameters:

module - The module to be removed

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

IllegalArgumentException - This exception is thrown if the input module is null

addConfiguration

public Configuration addConfiguration(Configuration configuration)
                               throws IOException,
                                      IotHubException,
                                      com.google.gson.JsonSyntaxException

Add configuration using the given Configuration object Return with the response configuration object from IotHub

Parameters:

configuration - The configuration object to add

Returns:

The configuration object for the requested operation

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getConfiguration

public Configuration getConfiguration(String configurationId)
                               throws IOException,
                                      IotHubException,
                                      com.google.gson.JsonSyntaxException

Get configuration by configuration Id from IotHub

Parameters:

configurationId - The id of requested configuration

Returns:

The configuration object of requested configuration on the specific device

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

getConfigurations

public List<Configuration> getConfigurations(Integer maxCount)
                                      throws IOException,
                                             IotHubException,
                                             com.google.gson.JsonSyntaxException

Get list of Configuration

Parameters:

maxCount - The requested count of configurations

Returns:

The array of requested configuration objects

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

updateConfiguration

public Configuration updateConfiguration(Configuration configuration)
                                  throws IOException,
                                         IotHubException

Update configuration not forced

Parameters:

configuration - The configuration object containing updated data

Returns:

The updated configuration object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

updateConfiguration

public Configuration updateConfiguration(Configuration configuration,
                                         Boolean forceUpdate)
                                  throws IOException,
                                         IotHubException,
                                         com.google.gson.JsonSyntaxException

Update configuration with forceUpdate input parameter

Parameters:

configuration - The configuration object containing updated data

forceUpdate - True if the update has to be forced regardless of the configuration state

Returns:

The updated configuration object

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

com.google.gson.JsonSyntaxException

removeConfiguration

public void removeConfiguration(String configurationId)
                         throws IOException,
                                IotHubException

Send remove configuration request and verify response

Parameters:

configurationId - The configuration to be removed

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

removeConfiguration

public void removeConfiguration(Configuration config)
                         throws IOException,
                                IotHubException,
                                IllegalArgumentException

Send remove configuration request and verify response

Parameters:

config - The configuration to be removed

Throws:

IOException - This exception is thrown if the IO operation failed

IotHubException - This exception is thrown if the response verification failed

IllegalArgumentException - This exception is thrown if the input configuration is null

applyConfigurationContentOnDevice

public void applyConfigurationContentOnDevice(String deviceId,
                                              ConfigurationContent content)
                                       throws IOException,
                                              IotHubException

Apply the provided configuration content to the provided device

Parameters:

deviceId - The device to apply the configuration to

content - The configuration content to apply to the device

Throws:

IOException - If the iot hub cannot be reached

IotHubException - If the response from the hub was an error code. This exception will contain that code