CloudioEndpoint (cloudio-endpoint-java 0.1.2 API)

java.lang.Object
- ch.hevs.cloudio.endpoint.CloudioEndpoint

All Implemented Interfaces:

CloudioEndpointService
```
public class CloudioEndpoint
extends java.lang.Object
implements CloudioEndpointService
```
An Endpoint is the root object of any connection of a device or a gateway to cloud.io. The parameters of the Endpoint can be either passed to the constructor as simple Java Properties or they can be present in a Java Properties file at the following locations (The Properties files are searched in the order of listing):
- ~/.config/cloud.io/{Endpoint UUID}.properties on the local file system.
- /etc/cloud.io/{Endpoint UUID}.properties on the local file system.
- cloud.io/{Endpoint UUID}.properties inside the application bundle.
Specifying resource locations:
When you specify a location for any configuration file or key/certificate file or any other kind of file, you need to use URIs to specify the file location. The following URI schemes are supported:
- classpath:
  The file is located in the classpath (Either in the JAR file or inside the same OSGi Bundle).
- file: The file is located on the local file system. An absolute path to the file has to be given.
- home: The file is located in the home directory of the actual user. The given path is relative to the user's home directory.
- http: The resource (file) is located on an HTTP server.
The properties configure all aspects of the communication between the endpoint and the cloud. Here the list of the supported properties:
- ch.hevs.cloudio.endpoint.hostUri
  URI of the cloud.io broker URI to connect to. An example might be "ssl://example.org:8883". Note that two schemes of connections are supported, "tcp" for non secure connections and "ssl" for secure connections. This property is mandatory.
- ch.hevs.cloudio.endpoint.connectTimeout
  Timeout in seconds to use when trying to connect to the cloud.io message broker. The default value is 5 seconds.
- ch.hevs.cloudio.endpoint.connectRetryInterval
  Interval in seconds to start a reconnect try after a connect failure. The default value is 10 seconds. If the value is 0, no connection retry has will be done at all once the connection is lost or could not be established.
- ch.hevs.cloudio.endpoint.keepAliveInterval
  Interval at which the client exchanges messages with the server in order to check that the connection is still alive and in order to guarantee that NAT port mappings remain. Default is 60 seconds.
- ch.hevs.cloudio.endpoint.persistence
  This option configures which persistence to use in order to save temporary data. Three options are possible:
  - memory
    The temporary data is saved into memory. With this option, pending messages (data) can be lost if the application is restarted. It is not advisable to use this persistence implementation in productive environments.
  - file
    The temporary data is saved onto the file system. Using this option, pending messages (data) will not be lost during a restart of the application if not a clean session is forced using the option ch.hevs.cloudio.endpoint.cleanSession.
  - none
    No Persistence is used at all. Using this persistence, messages (data) will be almost certain be lost, but if your application can handle such losses and you want to use as less as resources as possible, this might be a solution.
  This property is optional and the default is file.
- ch.hevs.cloudio.endpoint.ssl.clientCert
  Path to the client certificate file. The certificate file must be encoded in the PKCS12 key format and it needs to contain the client's certificate and the client's private key. The file has additionally to be encrypted and protected using a password. The password to use to decrypt the file is specified using the property ch.hevs.cloudio.endpoint.ssl.clientPassword.
  This property is optional and if the property is not set, the endpoint searches these locations in the given order for the JKCS12 file:
  - ~/.config/cloud.io/{Endpoint UUID}.p12 on the local file system.
  - /etc/cloud.io/{Endpoint UUID}.p12 on the local file system.
  - cloud.io/{Endpoint UUID}.p12 inside the application bundle (classpath).
- ch.hevs.cloudio.endpoint.ssl.clientPassword
  Password to unlock the PKCS12 archive containing the endpoint's certificate and private key. The PCKS12 file is specified using the ch.hevs.cloudio.endpoint.ssl.clientCert property. Note that it is not mandatory to encrypt the PKCS12 files.
  Optional, defaults to "" which means no password at all.
- ch.hevs.cloudio.endpoint.ssl.authorityCert
  The path to the certificate of the certification authority embedded into a JKS file.
- ch.hevs.cloudio.endpoint.ssl.authorityPassword
  Password to unlock the JKS archive containing the certification authority's certificate. The JKS file is specified using the ch.hevs.cloudio.endpoint.ssl.authorityCert property.
  Optional, defaults to "" which means no password at all.
- ch.hevs.cloudio.endpoint.ssl.protocol
  Specifies the SSL protocol to use. Possible values depend on the actual SSL implementation. Most commonly supported are:
  - SSL
  - SSLv2
  - SSLv3
  - TLS
  - TLSv1
  - TLSv1.1
  - TLSv1.2
  This property is optional and defaults to TLSv1.2.
- ch.hevs.cloudio.endpoint.messageFormat
  The message format used to communicate within cloud.io. Currently supported data formats are:
  - json: JSON Format.
  - json+zip: Compressed JSON.
  If this property is not set, the default "json" will be used. Note that it is important that all endpoints and applications in the same cloud.io installation use the very same message format, otherwise they will not be able to communicate with each other.
- ch.hevs.cloudio.endpoint.cleanSession
  This property can be either "true" or "false". If it is true, a clean MQTT session is established with the central broker. This means that pending messages from a previous session will be discarded. If it is "false" which is the default, pending messages from previous sessions will be send to the server upon the connection is established.

Constructor Summary

Constructors
Constructor	Description
`CloudioEndpoint(java.lang.String uuid)`	Constructs a new Endpoint object using the given UUID.
`CloudioEndpoint(java.lang.String uuid, java.util.Properties properties)`	Constructs a new CloudioEndpoint object using the given UUID and properties.
`CloudioEndpoint(java.lang.String uuid, java.util.Properties properties, CloudioEndpointListener listener)`	Constructs a new CloudioEndpoint object using the given UUID and properties.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`addEndpointListener(CloudioEndpointListener listener)`	Adds the given listener to the endpoint service.
`void`	`addNode(java.lang.String nodeName, CloudioNode node)`	Adds the given node to the endpoint.
`<T extends CloudioNode> T`	`addNode(java.lang.String nodeName, java.lang.Class<T> nodeClass)`	Adds a new node instance of the given node class to the endpoint.
`void`	`close()`
`<T extends CloudioNode> T`	`getNode(java.lang.String nodeName)`	Returns the node with the given name that was registered within cloud.iO or null if no such node is present.
`boolean`	`isOnline()`	Returns true if the endpoint is connected to the central message broker, otherwise false.
`void`	`removeEndpointListener(CloudioEndpointListener listener)`	Removes the given listener from the endpoint service.
`void`	`removeNode(CloudioNode node)`	Removes the given node from the endpoint if the node actually is part of the endpoint.
`void`	`removeNode(java.lang.String nodeName)`	Removes the node with the given name from the endpoint if the node actually is part of the endpoint.

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

- Constructor Detail
  - CloudioEndpoint
```
public CloudioEndpoint(java.lang.String uuid)
                throws InvalidUuidException,
                       InvalidPropertyException,
                       CloudioEndpointInitializationException
```
    Constructs a new Endpoint object using the given UUID. As no properties are given using this constructor, the properties are loaded from the file system or the actual bundle itself. The Java Properties file at the following locations (The Properties files are searched in the order of listing) are used:
    - ~/.config/cloud.io/{Endpoint UUID}.properties on the local file system.
    - /etc/cloud.io/{Endpoint UUID}.properties on the local file system.
    - ~{Endpoint UUID}.properties inside the application bundle (classpath).
    The endpoint will try immediately to connect to the central message broker and tries automatically to maintain this connection in the background.
    Parameters:
    
    uuid - Unique ID of the endpoint.
    
    Throws:
    
    InvalidUuidException - If the given UUID is invalid.
    
    InvalidPropertyException - Either a mandatory property is missing or a property has an invalid value.
    
    CloudioEndpointInitializationException - The endpoint could not be initialized. This might be caused by invalid parameters, invalid certificates or any other runtime errors.
  - CloudioEndpoint
```
public CloudioEndpoint(java.lang.String uuid,
                       java.util.Properties properties)
                throws InvalidUuidException,
                       InvalidPropertyException,
                       CloudioEndpointInitializationException
```
    Constructs a new CloudioEndpoint object using the given UUID and properties. The endpoint will try immediately to connect to the central message broker and tries automatically to maintain this connection in the background.
    
    Parameters:
    
    uuid - Unique ID of the endpoint.
    
    properties - Properties containing the endpoint configuration parameters.
    
    Throws:
    
    InvalidUuidException - If the given UUID is invalid.
    
    InvalidPropertyException - Either a mandatory property is missing or a property has an invalid value.
    
    CloudioEndpointInitializationException - The endpoint could not be initialized. This might be caused by invalid parameters, invalid certificates or any other runtime errors.
  - CloudioEndpoint
```
public CloudioEndpoint(java.lang.String uuid,
                       java.util.Properties properties,
                       CloudioEndpointListener listener)
                throws InvalidUuidException,
                       InvalidPropertyException,
                       CloudioEndpointInitializationException
```
    Constructs a new CloudioEndpoint object using the given UUID and properties. The endpoint will try immediately to connect to the central message broker and tries automatically to maintain this connection in the background. The given endpoint listener receives updates about the state of the endpoint.
    
    Parameters:
    
    uuid - Unique ID of the endpoint.
    
    properties - Properties containing the endpoint configuration parameters.
    
    listener - Reference to the listener receiving status updates.
    
    Throws:
    
    InvalidUuidException - If the given UUID is invalid.
    
    InvalidPropertyException - Either a mandatory property is missing or a property has an invalid value.
    
    CloudioEndpointInitializationException - The endpoint could not be initialized. This might be caused by invalid parameters, invalid certificates or any other runtime errors.
- Method Detail
  - close
```
public void close()
```
  - isOnline
```
public boolean isOnline()
```
    Description copied from interface: CloudioEndpointService
    
    Returns true if the endpoint is connected to the central message broker, otherwise false.
    
    Specified by:
    
    isOnline in interface CloudioEndpointService
    
    Returns:
    
    True if the endpoint is online, false otherwise.
  - addEndpointListener
```
public void addEndpointListener(CloudioEndpointListener listener)
```
    Description copied from interface: CloudioEndpointService
    
    Adds the given listener to the endpoint service.
    
    Specified by:
    
    addEndpointListener in interface CloudioEndpointService
    
    Parameters:
    
    listener - Listener to add.
  - removeEndpointListener
```
public void removeEndpointListener(CloudioEndpointListener listener)
```
    Description copied from interface: CloudioEndpointService
    
    Removes the given listener from the endpoint service.
    
    Specified by:
    
    removeEndpointListener in interface CloudioEndpointService
    
    Parameters:
    
    listener - Listener to add.
  - addNode
```
public void addNode(java.lang.String nodeName,
                    CloudioNode node)
             throws DuplicateNamedItemException
```
    Description copied from interface: CloudioEndpointService
    
    Adds the given node to the endpoint. The name of the node needs to be unique, otherwise the method will fail with an DuplicateNamedItemException.
    
    Specified by:
    
    addNode in interface CloudioEndpointService
    
    Parameters:
    
    nodeName - Name to give to the node.
    
    node - Reference to the node instance to add.
    
    Throws:
    
    DuplicateNamedItemException - If a node with the given name already exists.
  - addNode
```
public <T extends CloudioNode> T addNode(java.lang.String nodeName,
                                         java.lang.Class<T> nodeClass)
                                  throws InvalidCloudioNodeException,
                                         DuplicateNamedItemException
```
    Description copied from interface: CloudioEndpointService
    
    Adds a new node instance of the given node class to the endpoint. The name of the node needs to be unique, otherwise the method will fail with an DuplicateNamedItemException. Note that the node class must dispose a default constructor in order to let the method create an instance of the class.
    
    Specified by:
    
    addNode in interface CloudioEndpointService
    
    Type Parameters:
    
    T - Type of the node class.
    
    Parameters:
    
    nodeName - Name to give to the node.
    
    nodeClass - The class of the node to instantiate.
    
    Returns:
    
    Reference to the new instance of the given node class.
    
    Throws:
    
    DuplicateNamedItemException - If a node with the given name already exists.
    
    InvalidCloudioNodeException
  - removeNode
```
public void removeNode(CloudioNode node)
```
    Description copied from interface: CloudioEndpointService
    
    Removes the given node from the endpoint if the node actually is part of the endpoint. If the node was not contained in the endpoint, the method will do nothing at all.
    
    Specified by:
    
    removeNode in interface CloudioEndpointService
    
    Parameters:
    
    node - Node to remove.
  - removeNode
```
public void removeNode(java.lang.String nodeName)
```
    Description copied from interface: CloudioEndpointService
    
    Removes the node with the given name from the endpoint if the node actually is part of the endpoint. If the endpoint does not contain a node with the given name, the method will do nothing at all.
    
    Specified by:
    
    removeNode in interface CloudioEndpointService
    
    Parameters:
    
    nodeName - Name of the node to remove.
  - getNode
```
public <T extends CloudioNode> T getNode(java.lang.String nodeName)
                                  throws java.lang.ClassCastException
```
    Description copied from interface: CloudioEndpointService
    
    Returns the node with the given name that was registered within cloud.iO or null if no such node is present.
    
    Specified by:
    
    getNode in interface CloudioEndpointService
    
    Type Parameters:
    
    T - Subclass of node.
    
    Parameters:
    
    nodeName - Name of the node to return a reference to.
    
    Returns:
    
    A reference to registered node or null if no node with the given name exists.
    
    Throws:
    
    java.lang.ClassCastException - If the node could not be casted to the target type

Class CloudioEndpoint

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CloudioEndpoint

CloudioEndpoint

CloudioEndpoint

Method Detail

close

isOnline

addEndpointListener

removeEndpointListener

addNode

addNode

removeNode

removeNode

getNode