Getting started

A typical API usage is as follows:

Step 1 - Include the library

For using this API please reference in your application the file migratorydata-client.js which is located in the folder lib of the SKD package.

Step 2 - Specify where to connect to

Specify a cluster of one or more MigratoryData servers to which the JavaScript client will connect to using the API method MigratoryDataClient.setServers(). The JavaScript client will connect to only one of the MigratoryData servers you specified. But, defining two or more MigratoryData servers is recommended to achieve fault tolerance. Supposing the MigratoryData server to which the JavaScript client connected goes down, then the API will automatically reconnect the client to another MigratoryData server in the list.

Step 3 - Define the handler function for real-time messages

Use the API method MigratoryDataClient.setMessageHandler() to define the message handler, a function defined by your application that will handle the real-time messages received from a MigratoryData server. The 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:

  • subject - the subject of the message

  • content - the content of the message

  • type - the type of the message, which can be either MigratoryDataClient.MESSAGE_TYPE_SNAPSHOT,

    : MigratoryDataClient.MESSAGE_TYPE_UPDATE, MigratoryDataClient.MESSAGE_TYPE_HISTORICAL or MigratoryDataClient.MESSAGE_TYPE_RECOVERED

  • retained - indicate whether or not the message was retained by the cluster

  • qos - indicate the quality of the service of the message

  • replySubject - the subject to be used to reply to the received message, which acts as a request

  • compressed - indicate whether or not the message should be/was compressed (To use compression feature add library https://www.npmjs.com/package/pako to your project dependencies.)

Step 4 - Define the handler function for status notifications

Use the API method MigratoryDataClient.setStatusHandler() to define the status handler, a function defined by your application that will handle the status notifications. The 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:

  • type - the type of the status notification
  • info - the detail information of the status notification

Step 5 - Subscribe to subjects

Use the API method MigratoryDataClient.subscribe() to specify interest in receiving real-time messages having as subjects the strings provided in the parameter of this API method. You can call the API method MigratoryDataClient.subscribe() at any time to subscribe to further subjects. To unsubscribe from subscribed subjects, use the API method MigratoryDataClient.unsubscribe().

Step 6 - Connect to the MigratoryData cluster

Use the API method MigratoryDataClient.connect() to connect to the cluster.

Step 7 - Publish messages

Use the API method MigratoryDataClient.publish() to publish messages.

Step 8 - Handle the real-time messages and status notifications

Handle the received messages in your message handler defined above. Also, handle the status notifications in your status handler defined above.

Examples

Examples built with this API are available in the folder examples of the SDK package. Start with the README file which explains how to run them.