com.opendxl.client

Class DxlClient

java.lang.Object

com.opendxl.client.DxlClient

All Implemented Interfaces:

java.lang.AutoCloseable

public class DxlClient
extends java.lang.Object
implements java.lang.AutoCloseable

The DxlClient class is responsible for all communication with the Data Exchange Layer (DXL) fabric (it can be thought of as the "main" class). All other classes exist to support the functionality provided by the client.

The following example demonstrates the configuration of a DxlClient instance and connecting it to the fabric:

 DxlClientConfig config = DxlClientConfig.createDxlConfigFromFile("dxlclient.config");
 try (DxlClient client = new DxlClient(config)) {
     client.connect();

     // do work here
 }
 

NOTE: The preferred way to construct the client is with a try-with-resource statement as shown above. This ensures that resources associated with the client are properly cleaned up when the block is exited.

The following classes and packages support the client:

• DxlClientConfig: This class holds the information necessary to connect a DxlClient to the DXL fabric.
• com.opendxl.client.message: See this package for information on the different types of messages that can be exchanged over the DXL fabric
• com.opendxl.client.callback: See this package for information on registering "callbacks" that are used to receive messages via the DxlClient.
• ServiceRegistrationInfo: This class holds the information necessary to register a service with the DXL fabric.

Constructor Summary

Constructors

Constructor and Description
DxlClient(DxlClientConfig config) Constructor for the DxlClient

Method Summary

Modifier and Type	Method and Description
void	addEventCallback(java.lang.String topic, EventCallback callback) Adds a EventCallback to the client for the specified topic.
void	addEventCallback(java.lang.String topic, EventCallback callback, boolean subscribeToTopic) Adds a EventCallback to the client for the specified topic.
void	addRequestCallback(java.lang.String topic, RequestCallback callback) Adds a RequestCallback to the client for the specified topic.
void	addResponseCallback(java.lang.String topic, ResponseCallback callback) Adds a ResponseCallback to the client for the specified topic.
void	asyncRequest(Request request) Sends a Request message to a remote DXL service asynchronously.
void	asyncRequest(Request request, ResponseCallback callback) Sends a Request message to a remote DXL service asynchronously.
void	asyncRequest(Request request, ResponseCallback callback, long waitMillis) Sends a Request message to a remote DXL service asynchronously.
void	close() Destroys the client (releases all associated resources).
void	connect() Attempts to connect the client to the DXL fabric.
void	disconnect() Attempts to disconnect the client from the DXL fabric.
DxlClientConfig	getConfig() Returns the DxlClientConfig assoicated with the client
Broker	getCurrentBroker() Returns the Broker that the client is currently connected to.
java.lang.String	getReplyToTopic() Returns the name of the "reply-to" topic to use for communicating back to this client (responses to requests).
java.util.Set<java.lang.String>	getSubscriptions() Returns a Set containing the topics that the client is currently subscribed to
java.lang.String	getUniqueId() Returns the unique identifier of the client instance
boolean	isConnected() Whether the client is currently connected to the DXL fabric.
void	reconnect() Attempts to reconnect the client to the fabric.
void	registerServiceAsync(ServiceRegistrationInfo service) Registers a DXL service with the fabric asynchronously.
void	registerServiceSync(ServiceRegistrationInfo service, long timeout) Registers a DXL service with the fabric.
void	removeEventCallback(java.lang.String topic, EventCallback callback) Removes a EventCallback from the client for the specified topic.
void	removeEventCallback(java.lang.String topic, EventCallback callback, boolean unsubscribeFromTopic) Removes a EventCallback from the client for the specified topic.
void	removeRequestCallback(java.lang.String topic, RequestCallback callback) Removes a RequestCallback from the client for the specified topic.
void	removeResponseCallback(java.lang.String topic, ResponseCallback callback) Removes a RequestCallback from the client for the specified topic.
void	sendEvent(Event event) Attempts to deliver the specified Event message to the DXL fabric.
void	sendResponse(Response response) Attempts to deliver the specified Response message to the DXL fabric.
void	setDisconnectedStrategy(DisconnectedStrategy strategy) Sets the strategy to use if the client becomes unexpectedly disconnected from the broker.
void	setSocketFactory(javax.net.ssl.SSLSocketFactory socketFactory) Sets the SSL socket factory
void	subscribe(java.lang.String topic) Subscribes to the specified topic on the DXL fabric.
Response	syncRequest(Request request) Sends a Request message to a remote DXL service.
Response	syncRequest(Request request, long waitMillis) Sends a Request message to a remote DXL service.
void	unregisterServiceAsync(ServiceRegistrationInfo service) Unregisters (removes) a DXL service with from the fabric asynchronously.
void	unregisterServiceAsync(java.lang.String serviceId) Unregisters (removes) a DXL service with from the fabric asynchronously.
void	unregisterServiceSync(ServiceRegistrationInfo service, long timeout) Unregisters (removes) a DXL service from the fabric.
void	unsubscribe(java.lang.String topic) Unsubscribes from the specified topic on the DXL fabric.

Methods inherited from class java.lang.Object

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

Constructor Detail

DxlClient

public DxlClient(DxlClientConfig config)
          throws DxlException

Constructor for the DxlClient

Parameters:

config - The DXL client configuration (see DxlClientConfig)

Throws:

DxlException - If a DXL exception occurs

Method Detail

getUniqueId

public java.lang.String getUniqueId()

Returns the unique identifier of the client instance

Returns:

The unique identifier of the client instance

isConnected

public boolean isConnected()

Whether the client is currently connected to the DXL fabric.

Returns:

true if the client is connected, otherwise false

close

public final void close()
                 throws java.lang.Exception

Destroys the client (releases all associated resources).

NOTE: This method should rarely be called directly. Instead, the preferred way to construct the client is with a try-with-resource statement. This ensures that resources associated with the client are properly cleaned up when the block is exited as shown below:

 try (DxlClient client = new DxlClient(config)) {
     client.connect();

     // do work here
 }
 

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception

connect

public final void connect()
                   throws DxlException

Attempts to connect the client to the DXL fabric.

This method does not return until either the client has connected to the fabric or it has exhausted the number of retries configured for the client causing an exception to be raised.

Several attributes are available for controlling the client retry behavior:

• DxlClientConfig.getConnectRetries() : The maximum number of connection attempts for each Broker specified in the DxlClientConfig
• DxlClientConfig.getReconnectDelay() : The initial delay between retry attempts. The delay increases ("backs off") as subsequent connection attempts are made.
• DxlClientConfig.getReconnectBackOffMultiplier() : Multiples the current reconnect delay by this value on subsequent connect retries. For example, a current delay of 3 seconds with a multiplier of 2 would result in the next retry attempt being in 6 seconds.
• DxlClientConfig.getReconnectDelayRandom() : A randomness delay percentage (between 0.0 and 1.0) that is used to increase the current retry delay by a random amount for the purpose of preventing multiple clients from having the same retry pattern in the next retry attempt being in 6 seconds.
• DxlClientConfig.getReconnectDelayMax() : The maximum delay between retry attempts

Throws:

DxlException - If the client is unable to establish a connection or an error occurs

disconnect

public final void disconnect()
                      throws DxlException

Attempts to disconnect the client from the DXL fabric.

Throws:

DxlException - If a DXL exception occurs

reconnect

public final void reconnect()
                     throws DxlException

Attempts to reconnect the client to the fabric. When performing a reconnect, all existing topic subscriptions are restored.

Throws:

DxlException - If a DXL exception occurs

getCurrentBroker

public Broker getCurrentBroker()

Returns the Broker that the client is currently connected to. null is returned if the client is not currently connected to a Broker.

Returns:

The current Broker object the client is connected to or null if not connected

subscribe

public final void subscribe(java.lang.String topic)
                     throws DxlException

Subscribes to the specified topic on the DXL fabric. This method is typically used in conjunction with the registration of EventCallback instances via the addEventCallback(java.lang.String, com.opendxl.client.callback.EventCallback, boolean) method.

The following is a simple example of using this:

 final EventCallback myEventCallback =
     event -> {
         try {
             System.out.println("Received event: "
                 + new String(event.getPayload(), Message.CHARSET_UTF8));
         } catch (UnsupportedEncodingException ex) {
             ex.printStackTrace();
         }
     };
 client.addEventCallback("/testeventtopic", myEventCallback, false);
 client.subscribe("/testeventtopic");
 

NOTE: By default when registering an event callback the client will automatically subscribe to the topic. In this example the addEventCallback(java.lang.String, com.opendxl.client.callback.EventCallback, boolean) method is invoked with the subscribeToTopic parameter set to false preventing the automatic subscription.

Parameters:

topic - The topic to subscribe to

Throws:

DxlException - If a DXL exception occurs

unsubscribe

public final void unsubscribe(java.lang.String topic)
                       throws DxlException

Unsubscribes from the specified topic on the DXL fabric.

See the subscribe(java.lang.String) method for more information on subscriptions.

Parameters:

topic - The topic to unsubscribe from

Throws:

DxlException - If a DXL exception occurs

getSubscriptions

public java.util.Set<java.lang.String> getSubscriptions()

Returns a Set containing the topics that the client is currently subscribed to

Returns:

A Set containing the topics that the client is currently subscribed to

syncRequest

public Response syncRequest(Request request)
                     throws DxlException

Sends a Request message to a remote DXL service.

See the ServiceRegistrationInfo class for more information on DXL services.

The default wait time is 1 hour

Parameters:

request - The Request message to send to a remote DXL service

Returns:

The Response

Throws:

DxlException - If an error occurs or the operation times out

See Also:

WaitTimeoutException

syncRequest

public Response syncRequest(Request request,
                            long waitMillis)
                     throws DxlException

Sends a Request message to a remote DXL service.

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

request - The Request message to send to a remote DXL service

waitMillis - The amount of time (in milliseconds) to wait for the Response to the request. If the timeout is exceeded an exception will be raised.

Returns:

The Response

Throws:

DxlException - If an error occurs or the operation times out

See Also:

WaitTimeoutException

asyncRequest

public void asyncRequest(Request request,
                         ResponseCallback callback,
                         long waitMillis)
                  throws DxlException

Sends a Request message to a remote DXL service asynchronously. This method differs from syncRequest(com.opendxl.client.message.Request) due to the fact that it returns to the caller immediately after delivering the Request message to the DXL fabric (It does not wait for the corresponding Response to be received).

An optional ResponseCallback can be specified. This callback will be invoked when the corresponding Response message is received by the client.

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

request - The Request message to send to a remote DXL service

callback - An optional ResponseCallback that will be invoked when the corresponding Response message is received by the client.

waitMillis - The amount of time to wait for a Response before removing the callback

Throws:

DxlException - If a DXL exception occurs

asyncRequest

public void asyncRequest(Request request,
                         ResponseCallback callback)
                  throws DxlException

Sends a Request message to a remote DXL service asynchronously. This method differs from syncRequest(com.opendxl.client.message.Request) due to the fact that it returns to the caller immediately after delivering the Request message to the DXL fabric (It does not wait for the corresponding Response to be received).

An optional ResponseCallback can be specified. This callback will be invoked when the corresponding Response message is received by the client.

See the ServiceRegistrationInfo class for more information on DXL services.

The default wait time is 1 hour. After the wait time is exceeded the callback will be removed (no longer tracked).

Parameters:

request - The Request message to send to a remote DXL service

callback - An optional ResponseCallback that will be invoked when the corresponding Response message is received by the client.

Throws:

DxlException - If a DXL exception occurs

asyncRequest

public void asyncRequest(Request request)
                  throws DxlException

Sends a Request message to a remote DXL service asynchronously. This method differs from syncRequest(com.opendxl.client.message.Request) due to the fact that it returns to the caller immediately after delivering the Request message to the DXL fabric (It does not wait for a Response to be received).

Parameters:

request - The Request message to send to a remote DXL service

Throws:

DxlException - If a DXL exception occurs

sendEvent

public void sendEvent(Event event)
               throws DxlException

Attempts to deliver the specified Event message to the DXL fabric.

See the Message class for more information on message types, how they are delivered to remote clients, etc.

Parameters:

event - The Event to send

Throws:

DxlException - If a DXL exception occurs

sendResponse

public void sendResponse(Response response)
                  throws DxlException

Attempts to deliver the specified Response message to the DXL fabric. The fabric will in turn attempt to deliver the response back to the client who sent the corresponding Request.

See the Message class for more information on message types, how they are delivered to remote clients, etc.

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

response - The response to send

Throws:

DxlException - If a DXL exception occurs

addRequestCallback

public void addRequestCallback(java.lang.String topic,
                               RequestCallback callback)

Adds a RequestCallback to the client for the specified topic. The callback will be invoked when Request messages are received by the client on the specified topic. A topic of null indicates that the callback should receive Request messages for all topics (no filtering).

NOTE: Usage of this method is quite rare due to the fact that registration of RequestCallback instances with the client occurs automatically when registering a service. See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

topic - The topic to receive Request messages on. A topic of null indicates that the callback should receive Request messages for all topics (no filtering).

callback - The RequestCallback to be invoked when a Request message is received on the specified topic.

removeRequestCallback

public void removeRequestCallback(java.lang.String topic,
                                  RequestCallback callback)

Removes a RequestCallback from the client for the specified topic. This method must be invoked with the same arguments as when the callback was originally registered via addRequestCallback(java.lang.String, com.opendxl.client.callback.RequestCallback).

Parameters:

topic - The topic to remove the callback for

callback - The RequestCallback to be removed for the specified topic

See Also:

addRequestCallback(String, RequestCallback)

addResponseCallback

public void addResponseCallback(java.lang.String topic,
                                ResponseCallback callback)

Adds a ResponseCallback to the client for the specified topic. The callback will be invoked when Response messages are received by the client on the specified topic. A topic of null indicates that the callback should receive Response messages for all topics (no filtering).

NOTE: Usage of this method is quite rare due to the fact that the use of ResponseCallback instances are typically limited to invoking a remote DXL service via the asyncRequest(com.opendxl.client.message.Request, com.opendxl.client.callback.ResponseCallback, long) method.

Parameters:

topic - The topic to receive Request messages on. A topic of null indicates that the callback should receive Request messages for all topics (no filtering).

callback - The RequestCallback to be invoked when a Request message is received on the specified topic.

removeResponseCallback

public void removeResponseCallback(java.lang.String topic,
                                   ResponseCallback callback)

Removes a RequestCallback from the client for the specified topic. This method must be invoked with the same arguments as when the callback was originally registered via addRequestCallback(java.lang.String, com.opendxl.client.callback.RequestCallback).

Parameters:

topic - The topic to remove the callback for

callback - The RequestCallback to be removed for the specified topic

See Also:

addResponseCallback(String, ResponseCallback)

addEventCallback

public void addEventCallback(java.lang.String topic,
                             EventCallback callback,
                             boolean subscribeToTopic)
                      throws DxlException

Adds a EventCallback to the client for the specified topic. The callback will be invoked when Event messages are received by the client on the specified topic. A topic of null indicates that the callback should receive Event messages for all topics (no filtering).

Parameters:

topic - The topic to receive Event messages on. A topic of null indicates that the callback should receive Event messages for all topics (no filtering).

callback - The EventCallback to be invoked when a Event message is received on the specified topic.

subscribeToTopic - Indicates if the client should automatically subscribe (subscribe(java.lang.String)) to the topic.

Throws:

DxlException - If an error occurs

addEventCallback

public void addEventCallback(java.lang.String topic,
                             EventCallback callback)
                      throws DxlException

Adds a EventCallback to the client for the specified topic. The callback will be invoked when Event messages are received by the client on the specified topic. A topic of null indicates that the callback should receive Event messages for all topics (no filtering).

This variant of the "addEventCallback" methods will automatically subscribe (subscribe(java.lang.String)) to the topic. Use the addEventCallback(String, EventCallback, boolean) method variant with the subscribeToTopic parameter set to false to prevent automatically subscribing to the topic.

Parameters:

topic - The topic to receive Event messages on. A topic of null indicates that the callback should receive Event messages for all topics (no filtering).

callback - The EventCallback to be invoked when a Event message is received on the specified topic.

Throws:

DxlException - If an error occurs

removeEventCallback

public void removeEventCallback(java.lang.String topic,
                                EventCallback callback,
                                boolean unsubscribeFromTopic)
                         throws DxlException

Removes a EventCallback from the client for the specified topic. This method must be invoked with the same arguments as when the callback was originally registered via addEventCallback(java.lang.String, com.opendxl.client.callback.EventCallback, boolean).

Parameters:

topic - The topic to remove the callback for

callback - The EventCallback to be removed for the specified topic

unsubscribeFromTopic - Indicates if the client should also unsubscribe ((@link #unsubscribe)) from the topic.

Throws:

DxlException - If an error occurs

See Also:

addEventCallback(String, EventCallback, boolean)

removeEventCallback

public void removeEventCallback(java.lang.String topic,
                                EventCallback callback)
                         throws DxlException

Removes a EventCallback from the client for the specified topic. This method must be invoked with the same arguments as when the callback was originally registered via addEventCallback(java.lang.String, com.opendxl.client.callback.EventCallback, boolean).

This variant of the "removeEventCallback" methods will automatically unsubscribe (unsubscribe(java.lang.String)) to the topic. Use the removeEventCallback(String, EventCallback, boolean) method variant with the unsubscribeToTopic parameter set to false to prevent automatically unsubscribing to the topic.

Parameters:

topic - The topic to remove the callback for

callback - The EventCallback to be removed for the specified topic

Throws:

DxlException - If an error occurs

See Also:

addEventCallback(String, EventCallback)

registerServiceSync

public void registerServiceSync(ServiceRegistrationInfo service,
                                long timeout)
                         throws DxlException

Registers a DXL service with the fabric. The specified ServiceRegistrationInfo instance contains information about the service that is to be registered.

This method will wait for confirmation of the service registration for up to the specified timeout in milliseconds. If the timeout is exceeded an exception will be raised.

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

service - A ServiceRegistrationInfo instance containing information about the service that is to be registered.

timeout - The amount of time (in milliseconds) to wait for confirmation of the service registration. If the timeout is exceeded an exception will be raised.

Throws:

DxlException - If an error occurs

registerServiceAsync

public void registerServiceAsync(ServiceRegistrationInfo service)
                          throws DxlException

Registers a DXL service with the fabric asynchronously. The specified ServiceRegistrationInfo instance contains information about the service that is to be registered.

This method differs from registerServiceSync(com.opendxl.client.ServiceRegistrationInfo, long) due to the fact that it returns to the caller immediately after sending the registration message to the DXL fabric (It does not wait for registration confirmation before returning).

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

service - A ServiceRegistrationInfo instance containing information about the service that is to be registered.

Throws:

DxlException - If an error occurs

unregisterServiceSync

public void unregisterServiceSync(ServiceRegistrationInfo service,
                                  long timeout)
                           throws DxlException

Unregisters (removes) a DXL service from the fabric. The specified ServiceRegistrationInfo instance contains information about the service that is to be removed.

This method will wait for confirmation of the service unregistration for up to the specified timeout in milliseconds. If the timeout is exceeded an exception will be raised.

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

service - A ServiceRegistrationInfo instance containing information about the service that is to be unregistered.

timeout - The amount of time (in milliseconds) to wait for confirmation of the service unregistration. If the timeout is exceeded an exception will be raised.

Throws:

DxlException - If an error occurs

unregisterServiceAsync

public void unregisterServiceAsync(ServiceRegistrationInfo service)
                            throws DxlException

Unregisters (removes) a DXL service with from the fabric asynchronously. The specified ServiceRegistrationInfo instance contains information about the service that is to be removed.

This method differs from unregisterServiceSync(com.opendxl.client.ServiceRegistrationInfo, long) due to the fact that it returns to the caller immediately after sending the unregistration message to the DXL fabric (It does not wait for unregistration confirmation before returning).

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

service - A ServiceRegistrationInfo instance containing information about the service that is to be unregistered.

Throws:

DxlException - If an error occurs

unregisterServiceAsync

public void unregisterServiceAsync(java.lang.String serviceId)
                            throws DxlException

Unregisters (removes) a DXL service with from the fabric asynchronously. The specified service id of a service will be removed.

This method differs from unregisterServiceSync(com.opendxl.client.ServiceRegistrationInfo, long) due to the fact that it returns to the caller immediately after sending the unregistration message to the DXL fabric (It does not wait for unregistration confirmation before returning).

See the ServiceRegistrationInfo class for more information on DXL services.

Parameters:

serviceId - The service id of a service to be removed

Throws:

DxlException - If an error occurs

setDisconnectedStrategy

public void setDisconnectedStrategy(DisconnectedStrategy strategy)

Sets the strategy to use if the client becomes unexpectedly disconnected from the broker. By default the ReconnectDisconnectedStrategy is used.

Parameters:

strategy - The strategy to use if the client becomes unexpectedly disconnected from the broker. By default the ReconnectDisconnectedStrategy is used.

setSocketFactory

public void setSocketFactory(javax.net.ssl.SSLSocketFactory socketFactory)

Sets the SSL socket factory

Parameters:

socketFactory - The SSL socket factory

getReplyToTopic

public java.lang.String getReplyToTopic()

Returns the name of the "reply-to" topic to use for communicating back to this client (responses to requests).

Returns:

The name of the "reply-to" topic to use for communicating back to this client (responses to requests).

getConfig

public DxlClientConfig getConfig()

Returns the DxlClientConfig assoicated with the client

Returns:

The DxlClientConfig assoicated with the client