oracle.iot.client.enterprise

Class EnterpriseClient

java.lang.Object

oracle.iot.client.Client<VirtualDevice>

oracle.iot.client.enterprise.EnterpriseClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class EnterpriseClient
extends Client<VirtualDevice>

EnterpriseClient is a enterprise application, client of the Oracle IoT Cloud Service.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the resources used by this client.
StorageObject	createStorageObject(java.lang.String uri) Create a new StorageObject from the URI for a named object in storage.
StorageObject	createStorageObject(java.lang.String name, java.lang.String contentType) Create a new StorageObject that will have a name with the given object name prefixed with the application's ID and a directory separator.
VirtualDevice	createVirtualDevice(java.lang.String endpointId, DeviceModel deviceModel) Create an AbstractVirtualDevice instance with the given device model for the given device identifier.
Pageable<Device>	getActiveDevices(java.lang.String deviceModel) Get the active devices implementing the specified device model.
Application	getApplication() Get details on the IoT application for this client.
DeviceModel	getDeviceModel(java.lang.String deviceModelUrn) Get the DeviceModel for the device model urn.
Pageable<java.lang.String>	getDeviceModels() Get the list of device models available for this application.
Pageable<Device>	getDevices(java.util.Set<Device.Field> fields, Filter filter) Return a Pageable collection of Device.
static EnterpriseClient	newClient(java.lang.String appName) Creates an instance of EnterpriseClient associated with the specified IoT application.
static EnterpriseClient	newClient(java.lang.String appName, java.lang.Object context) Creates an instance of EnterpriseClient associated with the specified IoT application and with platform specific context.
static EnterpriseClient	newClient(java.lang.String configFilePath, java.lang.String configFilePassword) Creates an instance of EnterpriseClient using the configuration from the given file path and password.
static EnterpriseClient	newClient(java.lang.String configFilePath, java.lang.String configFilePassword, java.lang.String appName, java.lang.Object context) Creates an instance of EnterpriseClient associated with the specified IoT application.

Methods inherited from class java.lang.Object

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

Method Detail

newClient

public static EnterpriseClient newClient(java.lang.String appName)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Creates an instance of EnterpriseClient associated with the specified IoT application. The created instance will use a custom or default TrustedAssetsManager to store, load and handle the client configuration. See configuration for details.

Parameters:

appName - the name of the IoT application to connect with.

• If not null, a REST call is performed to find the application-id matching with the specified name.
• If null, a REST call is performed to find the application that has, in its list of integrations identifier, the one retrieved from the TrustedAssetsManager.

Returns:

an EnterpriseClient instance to communicate with the specified IoT application

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - if the trust material could not be loaded. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

See Also:

getApplication()

newClient

public static EnterpriseClient newClient(java.lang.String appName,
                                         java.lang.Object context)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Creates an instance of EnterpriseClient associated with the specified IoT application and with platform specific context. The created instance will use a custom or default TrustedAssetsManager to store, load and handle the client configuration. See configuration for details.

If the appName is not null, a REST call is performed to find the application-id matching with the specified name.
If the appName is null, a REST call is performed to find the application that has, in its list of integrations identifier, the one retrieved from the TrustedAssetsManager.

The specified context (if any) could be used by platform specific implementation to retrieve information like internal storage area.

Parameters:

appName - the name of the IoT application to connect with, or null.

context - a platform specific object (e.g. application context), that needs to be associated with this client. In the case of Android, this is an android.content.Context provided by the application or service. In the case of Java SE, the parameter is not used and the value may be null.

Returns:

an EnterpriseClient instance to communicate with the specified IoT application

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - if the trust material could not be loaded. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

newClient

public static EnterpriseClient newClient(java.lang.String configFilePath,
                                         java.lang.String configFilePassword,
                                         java.lang.String appName,
                                         java.lang.Object context)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Creates an instance of EnterpriseClient associated with the specified IoT application. The configuration will be loaded from the given path. See configuration for details.

If the appName is not null, a REST call is performed to find the application-id matching with the specified name.
If the appName is null, a REST call is performed to find the application that has, in its list of integrations identifier, the one retrieved from the TrustedAssetsManager.

The specified context (if any) could be used by platform specific implementation to retrieve information like internal storage area.

Parameters:

configFilePath - the path of the configuration file and may not be null

configFilePassword - the configuration file password, or null if the configurationFile is not encrypted

appName - the name of the IoT application to connect with, or null.

context - a platform specific object (e.g. application context), that needs to be associated with this client. In the case of Android, this is an android.content.Context provided by the application or service. In the case of Java SE, the parameter is not used and the value may be null.

Returns:

an EnterpriseClient instance to communicate with the specified IoT application

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - if the trust material could not be loaded. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

java.lang.IllegalArgumentException - if configFilePath is null

newClient

public static EnterpriseClient newClient(java.lang.String configFilePath,
                                         java.lang.String configFilePassword)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Creates an instance of EnterpriseClient using the configuration from the given file path and password. See configuration for details.

Parameters:

configFilePath - the path of the configuration file

configFilePassword - the configuration file password, or null if the configurationFile is not encrypted

Returns:

an EnterpriseClient instance to communicate with the specified IoT application

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - if the trust material could not be loaded. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

createVirtualDevice

public VirtualDevice createVirtualDevice(java.lang.String endpointId,
                                         DeviceModel deviceModel)

Create an AbstractVirtualDevice instance with the given device model for the given device identifier. This method creates a new VirtualDevice instance for the given parameters. The client library does not cache previously created VirtualDevice objects.

Specified by:

createVirtualDevice in class Client<VirtualDevice>

Parameters:

endpointId - The device identifier of the device being modeled

deviceModel - The device model URN that this device implements

Returns:

a new VirtualDevice

Throws:

java.lang.RuntimeException - if the network request to initialize the device with its current state fails and an IOException or GeneralSecurityException occurs. The cause will reflect the relevant exception.

close

public void close()
           throws java.io.IOException

Closes the resources used by this client.

Throws:

java.io.IOException - if an I/O error occurs

getApplication

public Application getApplication()

Get details on the IoT application for this client.

Returns:

details on the specified application

getDeviceModels

public Pageable<java.lang.String> getDeviceModels()
                                           throws java.io.IOException,
                                                  java.security.GeneralSecurityException

Get the list of device models available for this application.

Returns:

the list of device models

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

getDeviceModel

public DeviceModel getDeviceModel(java.lang.String deviceModelUrn)
                           throws java.io.IOException,
                                  java.security.GeneralSecurityException

Get the DeviceModel for the device model urn. This method may return null if there is no device model for the URN. Null may also be returned if the device model is a "draft" and the property com.oracle.iot.client.device.allow_draft_device_models is set to false, which is the default.

Specified by:

getDeviceModel in class Client<VirtualDevice>

Parameters:

deviceModelUrn - the URN of the device model

Returns:

A representation of the device model or null if it does not exist

Throws:

java.lang.NullPointerException - if deviceModel is null

java.io.IOException - if there is an I/O error when communicating with the server

java.security.GeneralSecurityException - when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

getActiveDevices

public Pageable<Device> getActiveDevices(java.lang.String deviceModel)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Get the active devices implementing the specified device model.

Parameters:

deviceModel - the URN of the device model

Returns:

devices that implements the specified device model

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

getDevices

public Pageable<Device> getDevices(java.util.Set<Device.Field> fields,
                                   Filter filter)
                            throws java.io.IOException,
                                   java.security.GeneralSecurityException

Return a Pageable collection of Device. The fields that will be available from returned Device instances will be limited to the one defined in fields. Use Device.Field.all() to get them all. The filter forms a query. Only devices that satisfy the filter and have a connectivity status of status are returned.

Parameters:

fields - set of fields Device.Field to return for the selected devices. Can be null.

filter - A filter. Can be null.

Returns:

an Pageable collection of Device that satisfy the filter and status. If no matching device is found, an Pageable with no elements is returned.

Throws:

java.io.IOException - if an I/O error occurred when trying to retrieve data from server

java.security.GeneralSecurityException - when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid. If User Authentication is used, then UserAuthenticationException will be thrown if the session cookie has expired.

createStorageObject

public StorageObject createStorageObject(java.lang.String name,
                                         java.lang.String contentType)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Create a new StorageObject that will have a name with the given object name prefixed with the application's ID and a directory separator. The prefix addition can be disabled by setting the com.oracle.iot.client.disable_storage_object_prefix to true.

If contentType is null, the mime-type defaults to "application/octet-stream".

Specified by:

createStorageObject in class Client<VirtualDevice>

Parameters:

name - the unique name to be used to reference the content in storage

contentType - The mime-type of the content or null

Returns:

a StorageObject

Throws:

java.io.IOException - if there is an IOException raised by the runtime, or an abnormal response from the storage cloud

java.security.GeneralSecurityException - if there is an exception establishing a secure connection to the storage cloud

createStorageObject

public StorageObject createStorageObject(java.lang.String uri)
                                  throws java.io.IOException,
                                         java.security.GeneralSecurityException

Create a new StorageObject from the URI for a named object in storage.

Parameters:

uri - the URI of the object in the storage cloud

Returns:

a StorageObject for the object in storage

Throws:

java.io.IOException - if there is an IOException raised by the runtime, or a failure reported by the storage cloud

java.security.GeneralSecurityException - if there is an exception establishing a secure connection to the storage cloud