public class DxlClient
extends java.lang.Object
implements java.lang.AutoCloseable
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 and Description |
---|
DxlClient(DxlClientConfig config)
Constructor for the
DxlClient |
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.
|
public DxlClient(DxlClientConfig config) throws DxlException
DxlClient
config
- The DXL client configuration (see DxlClientConfig
)DxlException
- If a DXL exception occurspublic java.lang.String getUniqueId()
public boolean isConnected()
true
if the client is connected, otherwise false
public final void close() throws java.lang.Exception
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 }
close
in interface java.lang.AutoCloseable
java.lang.Exception
public final void connect() throws DxlException
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
DxlException
- If the client is unable to establish a connection or an error occurspublic final void disconnect() throws DxlException
DxlException
- If a DXL exception occurspublic final void reconnect() throws DxlException
DxlException
- If a DXL exception occurspublic Broker getCurrentBroker()
Broker
that the client is currently connected to. null
is returned if the client is
not currently connected to a Broker
.public final void subscribe(java.lang.String topic) throws DxlException
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.
topic
- The topic to subscribe toDxlException
- If a DXL exception occurspublic final void unsubscribe(java.lang.String topic) throws DxlException
See the subscribe(java.lang.String)
method for more information on subscriptions.
topic
- The topic to unsubscribe fromDxlException
- If a DXL exception occurspublic java.util.Set<java.lang.String> getSubscriptions()
Set
containing the topics that the client is currently subscribed toSet
containing the topics that the client is currently subscribed topublic Response syncRequest(Request request) throws DxlException
Request
message to a remote DXL service.
See the ServiceRegistrationInfo
class for more information on DXL services.
1
hourrequest
- The Request
message to send to a remote DXL serviceResponse
DxlException
- If an error occurs or the operation times outWaitTimeoutException
public Response syncRequest(Request request, long waitMillis) throws DxlException
Request
message to a remote DXL service.
See the ServiceRegistrationInfo
class for more information on DXL services.
request
- The Request
message to send to a remote DXL servicewaitMillis
- The amount of time (in milliseconds) to wait for the Response
to the request.
If the timeout is exceeded an exception will be raised.Response
DxlException
- If an error occurs or the operation times outWaitTimeoutException
public void asyncRequest(Request request, ResponseCallback callback, long waitMillis) throws DxlException
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.
request
- The Request
message to send to a remote DXL servicecallback
- 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 callbackDxlException
- If a DXL exception occurspublic void asyncRequest(Request request, ResponseCallback callback) throws DxlException
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.
1
hour. After the wait time is exceeded the callback will be removed
(no longer tracked).request
- The Request
message to send to a remote DXL servicecallback
- An optional ResponseCallback
that will be invoked when the corresponding
Response
message is received by the client.DxlException
- If a DXL exception occurspublic void asyncRequest(Request request) throws DxlException
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).request
- The Request
message to send to a remote DXL serviceDxlException
- If a DXL exception occurspublic void sendEvent(Event event) throws DxlException
Event
message to the DXL fabric.
See the Message
class for more information on message types, how they are delivered to remote
clients, etc.
event
- The Event
to sendDxlException
- If a DXL exception occurspublic void sendResponse(Response response) throws DxlException
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.
response
- The response to sendDxlException
- If a DXL exception occurspublic void addRequestCallback(java.lang.String topic, RequestCallback callback)
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.
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.public void removeRequestCallback(java.lang.String topic, RequestCallback callback)
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)
.topic
- The topic to remove the callback forcallback
- The RequestCallback
to be removed for the specified topicaddRequestCallback(String, RequestCallback)
public void addResponseCallback(java.lang.String topic, ResponseCallback callback)
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.
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.public void removeResponseCallback(java.lang.String topic, ResponseCallback callback)
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)
.topic
- The topic to remove the callback forcallback
- The RequestCallback
to be removed for the specified topicaddResponseCallback(String, ResponseCallback)
public void addEventCallback(java.lang.String topic, EventCallback callback, boolean subscribeToTopic) throws DxlException
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).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.DxlException
- If an error occurspublic void addEventCallback(java.lang.String topic, EventCallback callback) throws DxlException
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.
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.DxlException
- If an error occurspublic void removeEventCallback(java.lang.String topic, EventCallback callback, boolean unsubscribeFromTopic) throws DxlException
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)
.topic
- The topic to remove the callback forcallback
- The EventCallback
to be removed for the specified topicunsubscribeFromTopic
- Indicates if the client should also unsubscribe ((@link #unsubscribe)) from the
topic.DxlException
- If an error occursaddEventCallback(String, EventCallback, boolean)
public void removeEventCallback(java.lang.String topic, EventCallback callback) throws DxlException
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.
topic
- The topic to remove the callback forcallback
- The EventCallback
to be removed for the specified topicDxlException
- If an error occursaddEventCallback(String, EventCallback)
public void registerServiceSync(ServiceRegistrationInfo service, long timeout) throws DxlException
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.
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.DxlException
- If an error occurspublic void registerServiceAsync(ServiceRegistrationInfo service) throws DxlException
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.
service
- A ServiceRegistrationInfo
instance containing information about the service that is to
be registered.DxlException
- If an error occurspublic void unregisterServiceSync(ServiceRegistrationInfo service, long timeout) throws DxlException
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.
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.DxlException
- If an error occurspublic void unregisterServiceAsync(ServiceRegistrationInfo service) throws DxlException
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.
service
- A ServiceRegistrationInfo
instance containing information about the service that is to
be unregistered.DxlException
- If an error occurspublic void unregisterServiceAsync(java.lang.String serviceId) throws DxlException
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.
serviceId
- The service id of a service to be removedDxlException
- If an error occurspublic void setDisconnectedStrategy(DisconnectedStrategy strategy)
ReconnectDisconnectedStrategy
is used.strategy
- The strategy to use if the client becomes unexpectedly disconnected
from the broker. By default the ReconnectDisconnectedStrategy
is used.public void setSocketFactory(javax.net.ssl.SSLSocketFactory socketFactory)
socketFactory
- The SSL socket factorypublic java.lang.String getReplyToTopic()
public DxlClientConfig getConfig()
DxlClientConfig
assoicated with the clientDxlClientConfig
assoicated with the client