This guide includes the following sections:

Overview

This application programming interface (API) contains all the necessary operations for connecting to a cluster of one or more MigratoryData servers, subscribing to subjects, getting real-time messages for the subscribed subjects, and publishing real-time messages.

Before reading this manual, it is recommended to read MigratoryData Architecture Guide (PDF, HTML).

Creating JavaScript clients for MigratoryData Server

A typical API usage is as follows:

Step 1 - Include the library

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

Step 2 - Specify the cluster of MigratoryData servers where to connect to

Use the API method MigratoryDataClient.setServers() to specify one or more MigratoryData servers to which your JavaScript client will connect to. In fact, the JavaScript client will connect to only one of the MigratoryData servers in this list. But, defining two or more MigratoryData servers is recommended to achieve fail-over. Supposing the MigratoryData server to which the JavaScript client connected goes down, then the API will automatically reconnect to another MigratoryData server in the list.

If you define two or more MigratoryData servers, then all the MigratoryData servers should provide the same level of data redundancy, by making available for subscription the same set of subjects.

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 web application that will handle the real-time messages received from a MigratoryData server. The message handler must have the following signature:

function <messageHandlerFunction>(Object messages);

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

subject - the subject of the message
content - the content of the message
fields - an array of fields where each field is an object with two properties: name (the name of the field) and value (the value of the field)
isSnapshot - indicate whether the message is an initial snapshot message or not

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 web 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 two properties:

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

Step 5 - Subscribe to subjects and publish messages

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().

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

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

Handle the received messages in your message handler defined above, and, optionally, handle the status notifications in your status handler defined above (you may choose to ignore the status notifications by not defining a status handler).

Examples

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