MigratoryDataClient

This class implements all the necessary operations for connecting to a cluster of one or more MigratoryData servers, subscribing to one or more subjects, getting real-time messages for the subscribed subjects, and publishing messages. More…

Public Functions

Public Attributes

Detailed Description

class MigratoryDataClient;

This class implements all the necessary operations for connecting to a cluster of one or more MigratoryData servers, subscribing to one or more subjects, getting real-time messages for the subscribed subjects, and publishing messages.

In this reference manual, are used type notations to better characterize the API. Python is a dynamic language that doesn’t have declared types, the type notations used in this document are only included to enhance the documentation.

Public Functions Documentation

function MigratoryDataClient

MigratoryDataClient()

Create a MigratoryDataClient object.

function connect

void connect()

Use this method to connect this client to one of the MigratoryData servers you specified with MigratoryDataClient.set_servers(), and subscribe to the subjects you specified with MigratoryDataClient.subscribe(), if any.

function set_listener

void set_listener(
    MigratoryDataListener listener
)

Attach a listener for handling the received real-time messages as well as the status notifications.

Parameters:

• listener an implementation of the MigratoryDataListener interface

function set_log_listener

void set_log_listener(
    MigratoryDataLogListener log_listener,
    MigratoryDataLogLevel log_level
)

Attach a listener for handling log messages outputted by the library.

Parameters:

• log_listener an implementation of the MigratoryDataLogListener interface
• log_level a particular MigratoryDataLogLevel configured as the logging threshold

It is advisable to configure this listener first to log as much as possible. If no log listener is set then, by default the client will log to the console.

function get_listener

MigratoryDataListener get_listener()

Get the listener for handling real-time messages and status notifications.

Return: the listener for handling real-time messages and status notifications

This is the listener set with MigratoryDataClient.set_listener().

function set_servers

void set_servers(
    String[] servers
)

Specify a cluster of one or more MigratoryData servers to which the client will connect to.

Parameters:

• servers an array of strings where each string represents the network address (IP address or DNS domain name and its corresponding port) of a MigratoryData server, optionally prefixed by a weight ranging from 0 to 100; if the weight prefix is not provided to an address, then the API will automatically assign to that address a default weight 100

For example, to connect to a cluster formed of two MigratoryData servers installed at the addresses p1.example.com and p2.example.com, and configured to accept clients on the standard HTTP port 80, the following code can be used:

client.set_servers(["p1.example.com:80", "p2.example.com:80"]);

To achieve load-balancing, the API connects the client to a MigratoryData server chosen randomly from the servers list. In this way, the load is balanced among all the members of the cluster.

Moreover, the API supports weighted load-balancing. This feature is especially useful if the MigratoryData servers of the cluster are installed on machines with different capacities. You can assign to each member of the cluster a weight ranging from 0 to 100. This weight assignment is a hint provided to the API to select with a higher probability a MigratoryData server with a higher weight either initially when the client connects to the cluster or later during a failover reconnection.

Supposing the address p1.example.com corresponds to a machine that is twice more powerful than the machine having the address p2.example.com, then you can assign to p1.example.com a weight 100 and to p2.example.com a weight 50 by prefixing each address with the assigned weight as follows:

client.set_servers(["100 p1.example.com:80", "50 p2.example.com:80"]);

The API assigns a default weight 100 to the addresses not prefixed with a specific weight.

To achieve failover, if the connection between the client and a MigratoryData server is broken, then the API will automatically detect the failure and will select another MigratoryData server from the servers list. If the client fails to connect to the newly selected server, a status notification MigratoryDataClient.NOTIFY_SERVER_DOWN will be triggered, unless this is modified using MigratoryDataClient.notify_after_failed_connection_attempts()), and a new MigratoryData server of the cluster will be selected again and again until the client will be able to connect to one of the MigratoryData servers of the cluster. When successfully connected, the API will trigger MigratoryDataClient.NOTIFY_SERVER_UP.

Furthermore, if the Guaranteed Message Delivery feature is enabled for the MigratoryData cluster, then the messages potentially published for a subscribed subject during the failover period will be automatically recovered from the cache of the MigratoryData server to which the client reconnects to and a status notification MigratoryDataClient.NOTIFY_DATA_SYNC will be triggered for that subject.

If, for example, the failover period is abnormally long, and the client is not able to recover all the messages made available during the failover period for one of its subscribed subjects, then the API will retrieve only the most recent retained message available for that subject and will trigger a MigratoryDataClient.NOTIFY_DATA_RESYNC status notification for that subject, the client behaving as a new client.

For a complete discussion about load balancing, failover, and guaranteed message delivery features see the Architecture Guide.

function subscribe

void subscribe(
    String[] subjects
)

Subscribe to one or more subjects.

Parameters:

• subjects An array of strings representing subjects.

The MigratoryData subjects are strings having a particular syntax. See the Chapter “Concepts” of the Architecture Guide to learn about the syntax of the subjects.

As an example, supposing messages are market data updates having as subjects stock names. Then, to subscribe for the messages having as subjects /stocks/NYSE/IBM and /stocks/Nasdaq/MSFT use:

client.subscribe(["/stocks/NYSE/IBM", "/stocks/Nasdaq/MSFT"]);

function unsubscribe

void unsubscribe(
    String[] subjects
)

Unsubscribe from one or more subjects.

Parameters:

• subjects subjects to unsubscribe

function set_encryption

void set_encryption(
    boolean encrypted
)

Configure whether to use SSL/TLS encryption when connecting to a MigratoryData server.

Parameters:

• encrypted indicate whether or not to use an encrypted SSL/TLS connection to communicate with the server

When using encryption you should connect to the ports of the MigratoryData server that are configured with the parameter ListenEncrypted to listen for encrypted connections.

function set_entitlement_token

void set_entitlement_token(
    String token
)

Assign an entitlement token to the client.

Parameters:

• token a string representing an entitlement token

To define which users of your application have access to which subjects, you will first have to configure the parameter Entitlement, see the Configuration Guide. If you set this parameter on Custom, then you can use the Server Extensions API for Authorization to build an extension for the MigratoryData server to allow or deny certain users to subscribe to or publish on certain subjects.

function get_subjects

Collection< String > get_subjects()

Return the list of subscribed subjects.

Return: The list of strings representing the subscribed subjects.

function disconnect

void disconnect()

Disconnect from the connected MigratoryData server and dispose the resources used by the connection.

This method should be called when the connection is no longer necessary.

function publish

void publish(
    MigratoryDataMessage message
)

Publish a message.

Parameters:

• message A MigratoryDataMessage message

If the message includes a closure data, then a status notification will be provided via MigratoryDataListener.on_status() to inform whether the message publication has been successful or failed.

function check_for_messages

bool check_for_messages()

Check to see if new messages are available.

Return: True if there are new messages to parse, otherwise None.

This method should be called in a while loop to check for new messages and to reconnect if the connection is broken.

while True:

    #check for sensors
    #do additional work

    # call this method to process the messages received by the API or to reconnect if the connection is broken.
    while client.check_for_messages() != None:
        pass

    time.sleep(5)

Public Attributes Documentation

variable NOTIFY_SERVER_UP

static final String NOTIFY_SERVER_UP = "NOTIFY_SERVER_UP";

A constant which indicates that the client successfully connected to a MigratoryData server.

variable NOTIFY_SERVER_DOWN

static final String NOTIFY_SERVER_DOWN = "NOTIFY_SERVER_DOWN";

A constant which indicates that the client failed to connect to a MigratoryData server.

variable NOTIFY_DATA_SYNC

static final String NOTIFY_DATA_SYNC = "NOTIFY_DATA_SYNC";

A constant which indicates that after a fail-over reconnection, the client successfully synchronized a subscribed subject with the latest retained message available for that subject, as well as with all messages made available published the fail-over period for that subject.

variable NOTIFY_DATA_RESYNC

static final String NOTIFY_DATA_RESYNC = "NOTIFY_DATA_RESYNC";

A constant which indicates that after a failover reconnection, the client successfully synchronized a subscribed subject with the latest retained message available for that subject, but not with the potential messages made available during the failover period, therefore behaving as a new client.

variable NOTIFY_CONNECT_OK

static final String NOTIFY_CONNECT_OK = "NOTIFY_CONNECT_OK";

A constant which indicates that the client was authorized to connect using the entitlement token defined on the client side.

variable NOTIFY_CONNECT_DENY

static final String NOTIFY_CONNECT_DENY = "NOTIFY_CONNECT_DENY";

A constant which indicates that the client was denied to connect using the entitlement token defined on the client side.

variable NOTIFY_SUBSCRIBE_ALLOW

static final String NOTIFY_SUBSCRIBE_ALLOW = "NOTIFY_SUBSCRIBE_ALLOW";

A constant which indicates that the client was authorized to subscribe to a subject.

variable NOTIFY_SUBSCRIBE_DENY

static final String NOTIFY_SUBSCRIBE_DENY = "NOTIFY_SUBSCRIBE_DENY";

A constant which indicates that the client was not authorized to subscribe to a subject.

variable NOTIFY_PUBLISH_OK

static final String NOTIFY_PUBLISH_OK = "NOTIFY_PUBLISH_OK";

A constant which indicates that the client successfully published a message.

variable NOTIFY_PUBLISH_FAILED

static final String NOTIFY_PUBLISH_FAILED = "NOTIFY_PUBLISH_FAILED";

A constant which indicates that the client was unable to publish a message.

variable NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED

static final String NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED = "NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED";

A constant which indicates that the client was unable to publish a message because the size of the message exceeds the message size limit allowed by the server (see the server parameter MaxMessageSize).

variable NOTIFY_PUBLISH_DENIED

static final String NOTIFY_PUBLISH_DENIED = "NOTIFY_PUBLISH_DENIED";

A constant which indicates that the client was not authorized to publish a message.