dxlclient.client module

Contains the DxlClient class, which is responsible for all communication with the Data Exchange Layer (DXL) fabric.

class dxlclient.client.DxlClient(config)

Bases: dxlclient._BaseObject

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:

from dxlclient.broker import Broker
from dxlclient.client import DxlClient
from dxlclient.client_config import DxlClientConfig

# Create the client configuration
config = DxlClientConfig(
    broker_ca_bundle="c:\\certs\\brokercerts.crt",
    cert_file="c:\\certs\\client.crt",
    private_key="c:\\certs\\client.key",
    brokers=[Broker.parse("ssl://192.168.189.12")])

# Create the DXL client
with DxlClient(config) as dxl_client:

    # Connect to the fabric
    dxl_client.connect()

NOTE: The preferred way to construct the client is via the Python "with" statement as shown above. The "with" statement ensures that resources associated with the client are properly cleaned up when the block is exited.

The following modules support the client:

  • dxlclient.client_config : See this module for information on configuring the DxlClient
  • dxlclient.message : See this module for information on the different types of messages that can be exchanged over the DXL fabric
  • dxlclient.callbacks : See this module for information on registering "callbacks" that are used to receive messages via the DxlClient. This module also includes an example that demonstrate how to send dxlclient.message.Event messages.
  • dxlclient.service : See this module for information on registering "services" with the DXL fabric. This module also includes an example that demonstrates how to invoke a DXL service via the DxlClient.

Constructor parameters:

Parameters:config -- The dxlclient.client_config.DxlClientConfig object containing the configuration settings for the client.
add_event_callback(topic, event_callback, subscribe_to_topic=True)

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

Parameters:
add_request_callback(topic, request_callback)

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

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

Parameters:
add_response_callback(topic, response_callback)

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

NOTE: Usage of this method is quite rare due to the fact that the use of dxlclient.callbacks.ResponseCallback instances are typically limited to invoking a remote DXL service via the async_request() method.

Parameters:
async_request(request, response_callback=None)

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

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

See module dxlclient.service for more information on DXL services.

Parameters:
config

The dxlclient.client_config.DxlClientConfig instance that was specified when the client was constructed.

See dxlclient.client_config for more information on configuring the client.

connect()

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:

connected

Whether the client is currently connected to the DXL fabric.

current_broker

The dxlclient.broker.Broker that the client is currently connected to. None is returned if the client is not currently connected to a dxlclient.broker.Broker.

destroy()

Destroys the client (releases all associated resources).

NOTE: Once the method has been invoked, no other calls should be made to the client.

Also note that this method should rarely be called directly. Instead, the preferred usage of the client is via a Python "with" statement as shown below:

# Create the DXL client
with DxlClient(config) as dxl_client:

    # Connect to the fabric
    dxl_client.connect()

The "with" statement ensures that resources associated with the client are properly cleaned up when the block is exited (the destroy() method is invoked).

disconnect()

Attempts to disconnect the client from the DXL fabric.

register_service_async(service_reg_info)

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

This method differs from register_service_sync() 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 dxlclient.service for more information on DXL services.

Parameters:service_reg_info -- A dxlclient.service.ServiceRegistrationInfo instance containing information about the service that is to be registered.
register_service_sync(service_req_info, timeout)

Registers a DXL service with the fabric. The specified dxlclient.service.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 seconds. If the timeout is exceeded an exception will be raised.

See dxlclient.service for more information on DXL services.

Parameters:
  • service_reg_info -- A dxlclient.service.ServiceRegistrationInfo instance containing information about the service that is to be registered.
  • timeout -- The amount of time (in seconds) to wait for confirmation of the service registration. If the timeout is exceeded an exception will be raised.
remove_event_callback(topic, event_callback, unsubscribe_from_topic=True)

Removes a dxlclient.callbacks.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 add_event_callback().

Parameters:
  • topic -- The topic to remove the callback for
  • event_callback -- The dxlclient.callbacks.EventCallback to be removed for the specified topic
  • unsubscribe_from_topic -- Optional parameter to indicate if the client should also unsubscribe (dxlclient.client.DxlClient.unsubscribe()) from the topic. By default the client will unsubscribe from the topic. Specify False to prevent unsubscribing to the topic.
remove_request_callback(topic, request_callback)

Removes a dxlclient.callbacks.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 add_request_callback().

Parameters:
remove_response_callback(topic, response_callback)

Removes a dxlclient.callbacks.ResponseCallback from the client for the specified topic. This method must be invoked with the same arguments as when the callback was originally registered via add_response_callback().

Parameters:
send_event(event)

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

See module dxlclient.message for more information on message types, how they are delivered to remote clients, etc.

Parameters:event -- The dxlclient.message.Event to send
send_response(response)

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

See module dxlclient.message for more information on message types, how they are delivered to remote clients, etc.

See module dxlclient.service for more information on DXL services.

Parameters:event -- The dxlclient.message.Event to send
subscribe(topic)

Subscribes to the specified topic on the DXL fabric. This method is typically used in conjunction with the registration of dxlclient.callbacks.EventCallback instances via the add_event_callback() method.

The following is a simple example of using this:

from dxlclient.callbacks import EventCallback

class MyEventCallback(EventCallback):
    def on_event(self, event):
        print("Received event! " + event.source_client_id)

dxl_client.add_event_callback("/testeventtopic", MyEventCallback(), False)
dxl_client.subscribe("/testeventtopic")

NOTE: By default when registering an event callback the client will automatically subscribe to the topic. In this example the dxlclient.client.DxlClient.add_event_callback() method is invoked with the subscribe_to_topic parameter set to False preventing the automatic subscription.

Parameters:topic -- The topic to subscribe to
subscriptions

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

See subscribe() for more information on adding subscriptions

sync_request(request, timeout=3600)

Sends a dxlclient.message.Request message to a remote DXL service.

See module dxlclient.service for more information on DXL services.

Parameters:
  • request -- The dxlclient.message.Request message to send to a remote DXL service
  • timeout -- The amount of time (in seconds) to wait for the dxlclient.message.Response to the request. If the timeout is exceeded an exception will be raised. Defaults to 3600 seconds (1 hour)
unregister_service_async(service_reg_info)

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

This method differs from unregister_service_sync() 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 dxlclient.service for more information on DXL services.

Parameters:service_reg_info -- A dxlclient.service.ServiceRegistrationInfo instance containing information about the service that is to be unregistered.
unregister_service_sync(service_req_info, timeout)

Unregisters (removes) a DXL service from the fabric. The specified dxlclient.service.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 seconds. If the timeout is exceeded an exception will be raised.

See dxlclient.service for more information on DXL services.

Parameters:
  • service_reg_info -- A dxlclient.service.ServiceRegistrationInfo instance containing information about the service that is to be removed.
  • timeout -- The amount of time (in seconds) to wait for confirmation of the service unregistration. If the timeout is exceeded an exception will be raised.
unsubscribe(topic)

Unsubscribes from the specified topic on the DXL fabric.

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

Parameters:topic -- The topic to unsubscribe from