MigratoryDataClient

More…

Public Functions

Name
void connect()
Use this method to connect this client to one of the MigratoryData servers you specified with MigratoryDataClient.setServers(), and subscribe to the subjects you specified with MigratoryDataClient.subscribe(), if any.
void setServers(string[] servers)
Specify a cluster of one or more MigratoryData servers to which the client will connect to.
void setMessageHandler(function messageHandler)
Specify a custom function name used to process the messages received from the MigratoryData cluster.
void setStatusHandler(function statusHandler)
Specify a custom function name used to process the status notifications.
void setEntitlementToken(string token)
Assign an entitlement token to the client.
void subscribe(string[] subjects)
Subscribe to one or more subjects.
void subscribeWithHistory(string[] subjects, int numberOfHistoricalMessages)
Subscribe to one or more subjects after getting historical messages for those subjects.
void unsubscribe(string[] subjects)
Unsubscribe from one or more subjects.
void publish(Object message)
Publish a message.
string[] getSubjects()
Get the list of subscribed subjects.
void notifyAfterFailedConnectionAttempts(int retries)
Define the number of failed attempts to connect to the MigratoryData cluster before triggering the status notification MigratoryDataClient.NOTIFY_SERVER_DOWN.
void setQuickReconnectInitialDelay(int seconds)
Define the number of seconds to wait before attempting to reconnect to the cluster after a connection failure is detected.
void setQuickReconnectMaxRetries(int retries)
Define the maximum number of retries for the Quick Reconnect Phase.
void setReconnectPolicy(string policy)
Define the reconnect policy to be used after the Quick Reconnect Phase.
void setReconnectTimeInterval(int seconds)
Define the time interval used for the reconnect schedule after the Quick Reconnect Phase.
void setReconnectMaxDelay(int seconds)
Define the maximum reconnect delay for the MigratoryDataClient.TRUNCATED_EXPONENTIAL_BACKOFF policy.
void disconnect()
Disconnect from the MigratoryData cluster and dispose the resources used by the connection.
string getInfo()
Return various statistical information.
void setTransport(string type)
Define the transport type used by the client to communicate with the MigratoryData cluster.
void setHttpHeader(string name, string value)
This method allows for the inclusion of custom HTTP headers.
void setDnsOptions(Object options)
Define the DNS method to be used to resolve host names.
void setLogHandler(function logHandler)
Specify a custom function name used to process the api log messages.

Public Attributes

Name
string NOTIFY_SERVER_UP
A constant which indicates that the client successfully connected to a MigratoryData server.
string NOTIFY_SERVER_DOWN
A constant which indicates that the client failed to connect to a MigratoryData server.
string NOTIFY_DATA_SYNC
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, as well as with all messages made available during the failover period for that subject.
string 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.
string NOTIFY_CONNECT_OK
A constant which indicates that the client is allowed to connect for the reason provided in the detail information of the status notification.
This notification applies when using a Custom authorization extension built with Auth API. For the entitlement methods None, Basic, or Custom authorization extension built with the previous version of the MigratoryData Extensions API, this notification is always sent no matter the entitlement token is valid or not, the verification of the entitlement token being made only during subscribe and publish operations.
string NOTIFY_CONNECT_DENY
A constant which indicates that the client is denied to connect for the reason provided in the detail information of the status notification.
This notification applies when using a Custom authorization extension built with Auth API. For the entitlement methods None, Basic, or Custom authorization extension built with the previous version of the MigratoryData Extensions API, this notification is never sent no matter the entitlement token is valid or not, the verification of the entitlement token being made only during subscribe and publish operations.
string NOTIFY_SUBSCRIBE_ALLOW
A constant which indicates that the client was authorized to subscribe to a subject.
string NOTIFY_SUBSCRIBE_DENY
A constant which indicates that the client was not authorized to subscribe to a subject.
string NOTIFY_PUBLISH_OK
A constant which indicates that the client successfully published a message.
string NOTIFY_PUBLISH_FAILED
A constant which indicates that the client was unable to publish a message.
string 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).
string NOTIFY_PUBLISH_DENIED
A constant which indicates that the client was unable to publish a message because it is not allowed by the entitlement system.
string CONSTANT_WINDOW_BACKOFF
A constant used to define the reconnect policy.
string TRUNCATED_EXPONENTIAL_BACKOFF
A constant used to define a reconnect policy.
string TRANSPORT_HTTP
A constant used to define the transport type.
string TRANSPORT_WEBSOCKET
A constant used to define the transport type.
string QOS_STANDARD
A constant which indicates the quality of the service STANDARD of a message.
string QOS_GUARANTEED
A constant which indicates the quality of the service GUARANTEED of a message.
string MESSAGE_TYPE_SNAPSHOT
A constant which indicates the message type of the message received from the server.
string MESSAGE_TYPE_UPDATE
A constant which indicates the message type of the message received from the server.
string MESSAGE_TYPE_RECOVERED
A constant which indicates the message type of the message received from the server.
string MESSAGE_TYPE_HISTORICAL
A constant which indicates the message type of the message received from the server.

Detailed Description

class MigratoryDataClient;

This class contains 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 real-time messages.

In this reference manual, the following type notations are used: int, string, bool, void, and string[] (indicating an array of strings) to better characterize the API. JavaScript 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 connect

void connect()

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

function setServers

void setServers(
    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:

var servers = new Array("http://p1.example.com:80", "http://p2.example.com:80");
MigratoryDataClient.setServers(servers);

or, given the fact that the standard HTTP port 80 is used by default for URLs, and using the JavaScript square bracket notation for arrays, a more concise JavaScript code can be used:

MigratoryDataClient.setServers(["http://p1.example.com", "http://p2.example.com"]);

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:

MigratoryDataClient.setServers(["100 http://p1.example.com", "50 http://p2.example.com"]);

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.notifyAfterFailedConnectionAttempts(), 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 potentialy 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 setMessageHandler

void setMessageHandler(
    function messageHandler
)

Specify a custom function name used to process the messages received from the MigratoryData cluster.

Parameters:

  • messageHandler A custom function used to handle the messages received from the MigratoryData cluster

This API call is used to define the message handler which is a function defined by your application that will handle the messages received from the MigratoryData cluster. Your message handler must have the following signature:

function <messageHandlerFunction>(Object message);

where <messageHandlerFunction> can be any function name of your choice. Its message argument is an object having the following properties:

If compression is enabled with this field for a message to publish but the size of the content of the message is smaller than the size of ZLIB-compressed content, then the message will be sent uncompressed to save bandwidth and CPU cycles with the decompression on the receiver side.

If the received message was compressed, the library automatically decompresses its content without any additional code.

To use compression feature add library https://www.npmjs.com/package/pako to your project dependencies.

This is a code example:

MigratoryDataClient.setMessageHandler(messageHandler);

function messageHandler(message) {
   console.log("Got message: " + message.subject + " = " + message.content);
}

function setStatusHandler

void setStatusHandler(
    function statusHandler
)

Specify a custom function name used to process the status notifications.

Parameters:

  • statusHandler A custom function used to handle the status notifications

This API call is used to define the status handler which is a function defined by your application that will handle the status notifications. Your status handler must have the following signature:

function <statusHandlerFunction>(Object status);

where statusHandlerFunction can be any function name of your choice. Its status argument is an object having the following properties:

This is a code example:

MigratoryDataClient.setStatusHandler(function(status) {
   console.log("Got status notification, type = " + status.type + ", info = " + status.info);
});

function setEntitlementToken

void setEntitlementToken(
    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 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 messages having as subjects /stocks/NYSE/IBM and /stocks/Nasdaq/MSFT the following code will be used:

var subjects = new Array("/stocks/NYSE/IBM", "/stocks/Nasdaq/MSFT");
MigratoryDataClient.subscribe(subjects);

or more simple, using the JavaScript square bracket notation for arrays:

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

function subscribeWithHistory

void subscribeWithHistory(
    string[] subjects,
    int numberOfHistoricalMessages
)

Subscribe to one or more subjects after getting historical messages for those subjects.

Parameters:

  • subjects an array of strings representing subjects
  • numberOfHistoricalMessages the number of historical messages to be retrieved from the cache

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.

Attempt to get the number of historical messages as defined by the argument numberOfHistoricalMessages, for each subject in the argument subjects, then subscribe for real-time messages having as subjects the strings provided in the subjects parameter.

When Guranteed Message Delivery is enabled, each MigratoryData server of the cluster maintains an in-memory cache with historical messages for each subject. The cache of each subject is available in all servers of the cluster. The maximum number of messages held in cache is defined by the parameter MaxCachedMessagesPerSubject of the MigratoryData server which defaults to 1000 messages. The historical messages are continuously removed from the cache, but it is guaranteed that they are available in the cache at least the number of seconds defined by the parameter CacheExpireTime which defaults to 180 seconds.

If the value of numberOfHistoricalMessages is higher then the number of historical messages available in the cache, then the client will receive only the messages available in the cache. As a consequence, if you use a value higher than the value of the parameter MaxCachedMessagesPerSubject of the MigratoryData server, then you will get the entire cache before subscribing for real-time messages for the subjects specified with this API method.

If the value of numberOfHistoricalMessages is 0, then no historical messages have to be retrieved from the cache and, in this case, this API method is equivalent to the API method MigratoryDataClient.subscribe().

function unsubscribe

void unsubscribe(
    string[] subjects
)

Unsubscribe from one or more subjects.

Parameters:

  • subjects an array of strings representing subjects

Unsubscribe from the subscribed subjects provided by the subjects parameter.

function publish

void publish(
    Object message
)

Publish a message.

Parameters:

  • message a MigratoryData message

A MigratoryData message is an object having the following properties:

If the message includes a replySubject, then it acts as a request because the publisher client will automatically subscribe to that reply subject. In this way, the subscriber clients which receive the message, will be able to reply by sending back a response message on replySubject. Therefore, this property can be used to implement a request/reply communication pattern, besides the usual publish/subscribe pattern.

If the message includes a qos, then the following possibilities arise, depending whether the MigratoryData cluster has been configured to use Guaranteed Message Delivery (GMD) or not:

If the message does not include a retained property, then by default the message will be retained by the cluster.

function getSubjects

string[] getSubjects()

Get the list of subscribed subjects.

Return: an array of strings representing the subscribed subjects

function notifyAfterFailedConnectionAttempts

void notifyAfterFailedConnectionAttempts(
    int retries
)

Define the number of failed attempts to connect to the MigratoryData cluster before triggering the status notification MigratoryDataClient.NOTIFY_SERVER_DOWN.

Parameters:

function setQuickReconnectInitialDelay

void setQuickReconnectInitialDelay(
    int seconds
)

Define the number of seconds to wait before attempting to reconnect to the cluster after a connection failure is detected.

Parameters:

  • seconds the number of seconds to wait before attempting to reconnect to the cluster; the default value is 5
Connection Failure Detection

A connection failure is detected immediately for almost all users running modern browsers. For a few users running modern browsers (and being subject to temporary, atypical network conditions) as well as for all users running older browsers without WebSocket support, connection failure is detected after about 30 seconds.

Reconnection Phases and Policies

When a connection failure is detected, the API will attempt to reconnect to the servers of the MigratoryData cluster as follows:

First, it will attempt to reconnect up to a number of times as defined by MigratoryDataClient.setQuickReconnectMaxRetries() using small delays between retries (Quick Reconnection Phase).

If the connection cannot be established after the Quick Reconnection Phase, then the API will attempt to reconnect less frequently according to the policy defined by MigratoryDataClient.setReconnectPolicy().

The delays between retries are computed according to the following algoritm where the values of the variables involved are defined by the API methods having substantially the same names:

Quick Reconnect Phase (retries <= quickReconnectMaxRetries)
-----------------------------------------------------------

   (retries starts with 1 and increment by 1 at each quick reconnect)

   reconnectDelay = quickReconnectInitialDelay * retries - random(0, quickReconnectInitialDelay)

After Quick Reconnect Phase (retries > quickReconnectMaxRetries)
----------------------------------------------------------------

   (reset retries to start with 1 and increment by 1 at each reconnect)

   If reconnectPolicy is CONSTANT_WINDOW_BACKOFF, then

      reconnectDelay = reconnectTimeInterval

   else if reconnectPolicy is TRUNCATED_EXPONENTIAL_BACKOFF, then

      reconnectDelay = min(reconnectTimeInterval * (2 ^ retries) - random(0, reconnectTimeInterval * retries), reconnectMaxDelay)

For the few users running modern browsers (and being subject to temporary, atypical network conditions) as well as for all users running older browsers without WebSocket support, if reconnectDelay computed with the algorithm above is less than 10 seconds, then it is rounded to 10 seconds.

function setQuickReconnectMaxRetries

void setQuickReconnectMaxRetries(
    int retries
)

Define the maximum number of retries for the Quick Reconnect Phase.

Parameters:

  • retries the maximum number of quick reconnect retries; the default value is 3

See MigratoryDataClient.setQuickReconnectInitialDelay() to learn about the Quick Reconnect Phase.

function setReconnectPolicy

void setReconnectPolicy(
    string policy
)

Define the reconnect policy to be used after the Quick Reconnect Phase.

Parameters:

The possible values for the policy argument are:

function setReconnectTimeInterval

void setReconnectTimeInterval(
    int seconds
)

Define the time interval used for the reconnect schedule after the Quick Reconnect Phase.

Parameters:

  • seconds the number of seconds used for reconnect schedule; the default is 20

See MigratoryDataClient.setQuickReconnectInitialDelay() to learn about the Quick Reconnect Phase and how the value defined by this API method is used for the reconnect schedule.

function setReconnectMaxDelay

void setReconnectMaxDelay(
    int seconds
)

Define the maximum reconnect delay for the MigratoryDataClient.TRUNCATED_EXPONENTIAL_BACKOFF policy.

Parameters:

See MigratoryDataClient.setQuickReconnectInitialDelay() to learn how the value defined by this API method is used.

function disconnect

void disconnect()

Disconnect from the MigratoryData cluster and dispose the resources used by the connection.

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

function getInfo

string getInfo()

Return various statistical information.

Return: a string with various statistical information useful for debugging or logging

function setTransport

void setTransport(
    string type
)

Define the transport type used by the client to communicate with the MigratoryData cluster.

Parameters:

In order for the client to communicate with a MigratoryData server using websockets, call this method with the argument MigratoryDataClient.TRANSPORT_WEBSOCKET. The websockets transport is provided by the Node.js library ws. So, in order to use this transport, make sure you install the package ws, using for example the npm command: npm i ws.

function setHttpHeader

void setHttpHeader(
    string name,
    string value
)

This method allows for the inclusion of custom HTTP headers.

Parameters:

  • name header name.
  • value header value.

This method allows for the inclusion of custom HTTP headers. In the case of the WebSocket transport, the added headers are transmitted during the handshake. For the HTTP transport, the added headers are sent with every client request.

This functionality is particularly useful when an authentication solution is in place between the client and the MigratoryData server, which requires an HTTP header containing an authentication token.

This method should be used only for Node.js applications.

function setDnsOptions

void setDnsOptions(
    Object options
)

Define the DNS method to be used to resolve host names.

Parameters:

  • options Object { dnsResolve: false|true } setting the property dnsResolve to true, the host names will be resolved using the method dns.resolve4(). Moreover, if multiple IP addresses exist for a host name, a new IP address is randomly selected from the list, different from the one selected during the previous resolve. Otherwise the host names will be resolved using the dns.lookup(). The default value is false.

Remark: This method should be used only for Node.js applications, not for web applications.

function setLogHandler

void setLogHandler(
    function logHandler
)

Specify a custom function name used to process the api log messages.

Parameters:

  • logHandler A custom function used to handle the api log messages.

This API call is used to define the log handler which is a function defined by your application to handle the log messages. If no log handler is set, then the API will send all logs to console.log.

Your log handler must have the following signature:

function _<logHandlerFunction>_(Object message);

where _<logHandlerFunction>_ can be any function name of your choice. Its message argument is an object of type string:

This is a code example:

MigratoryDataClient.setLogHandler(function(message) {
       console.log(message);
});

Public Attributes Documentation

variable NOTIFY_SERVER_UP

string NOTIFY_SERVER_UP;

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

variable NOTIFY_SERVER_DOWN

string NOTIFY_SERVER_DOWN;

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

variable NOTIFY_DATA_SYNC

string NOTIFY_DATA_SYNC;

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, as well as with all messages made available during the failover period for that subject.

variable NOTIFY_DATA_RESYNC

string 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

string 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

string NOTIFY_CONNECT_DENY;

variable NOTIFY_SUBSCRIBE_ALLOW

string NOTIFY_SUBSCRIBE_ALLOW;

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

variable NOTIFY_SUBSCRIBE_DENY

string NOTIFY_SUBSCRIBE_DENY;

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

variable NOTIFY_PUBLISH_OK

string NOTIFY_PUBLISH_OK;

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

variable NOTIFY_PUBLISH_FAILED

string NOTIFY_PUBLISH_FAILED;

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

variable NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED

string 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

string NOTIFY_PUBLISH_DENIED;

A constant which indicates that the client was unable to publish a message because it is not allowed by the entitlement system.

variable CONSTANT_WINDOW_BACKOFF

string CONSTANT_WINDOW_BACKOFF;

A constant used to define the reconnect policy.

See MigratoryDataClient.setQuickReconnectInitialDelay() for more details about this policy.

variable TRUNCATED_EXPONENTIAL_BACKOFF

string TRUNCATED_EXPONENTIAL_BACKOFF;

A constant used to define a reconnect policy.

See MigratoryDataClient.setQuickReconnectInitialDelay() for more details about this policy.

variable TRANSPORT_HTTP

string TRANSPORT_HTTP;

A constant used to define the transport type.

See MigratoryDataClient.setTransport() for more details about this policy.

variable TRANSPORT_WEBSOCKET

string TRANSPORT_WEBSOCKET;

A constant used to define the transport type.

See MigratoryDataClient.setTransport() for more details about this policy.

variable QOS_STANDARD

string QOS_STANDARD;

A constant which indicates the quality of the service STANDARD of a message.

variable QOS_GUARANTEED

string QOS_GUARANTEED;

A constant which indicates the quality of the service GUARANTEED of a message.

variable MESSAGE_TYPE_SNAPSHOT

string MESSAGE_TYPE_SNAPSHOT;

A constant which indicates the message type of the message received from the server.

variable MESSAGE_TYPE_UPDATE

string MESSAGE_TYPE_UPDATE;

A constant which indicates the message type of the message received from the server.

variable MESSAGE_TYPE_RECOVERED

string MESSAGE_TYPE_RECOVERED;

A constant which indicates the message type of the message received from the server.

variable MESSAGE_TYPE_HISTORICAL

string MESSAGE_TYPE_HISTORICAL;

A constant which indicates the message type of the message received from the server.