Examples

Create a directory and install MigratoryData NodeJS API library:

mkdir echo-example
cd echo-example
npm install migratorydata-client@~6.0.10

Copy the code below to a file named echo.js.

require("migratorydata-client");

function publish() {
    var date = new Date();
    var time = date.getTime();

    client.publish({
        subject : "/server/status",
        content : "content-" + time,
        closure : "id-" + time
    });
}

var client = new MigratoryDataClient();

client.setMessageHandler(function(message) {
    console.log("Got message : [ " + message.subject + " = " + message.content + " ]");
});

client.setStatusHandler(function(event) {
    console.log("Status : " + event.type + " : " + event.info);

    // publication starts once it gets NOTIFY_SERVER_UP
    if (event.type == MigratoryDataClient.NOTIFY_SERVER_UP) {
        publish();
    }

    // next publication should be performed once the client
    // gets the status of the previous publication
    if (event.type ==  MigratoryDataClient.NOTIFY_PUBLISH_OK) {
        // publish a new message after let's say 1000 milliseconds
        setTimeout(function() {
            publish();
        }, 1000);
    }

    if (event.type ==  MigratoryDataClient.NOTIFY_PUBLISH_FAILED) {
        // the previous message should be republished here
    }

    if (event.type ==  MigratoryDataClient.NOTIFY_PUBLISH_DENIED) {
        console.log("Check your entitlement token");
    }
});

client.setEntitlementToken("some-token");
client.setServers([ "http://127.0.0.1:8800" ]);
client.subscribe([ "/server/status" ]);

client.connect();

The client application connects to the MigratoryData server deployed at 127.0.0.1:8800, subscribes to a subject /server/status, publishes to the MigratoryData server a message every second on the same subject, and receives from the MigratoryData server the published message.

If you don’t have a MigratoryData server installed on your machine but there is docker installed you can run the following command to start MigratoryData server, otherwise you can download and install the latest version for your os from here.

docker pull migratorydata/server:latest
docker run --platform linux/amd64 -d --name my_migratorydata -p 8800:8800 migratorydata/server:latest

Next, run the application using commands:

node echo.js

To test the application, connect to the MigratoryData server via browser at http://localhost:8800 and go to Debug Console. Subscribe and publish data to subject /server/status and see if the application is receiving data. Also you should receive data published by the application.

A typical API usage is as follows:

Step 1 - Install the library

Install the MigratoryData library using the npm command as follows:

npm i migratorydata-client

Step 2 - Specify where to connect to

Specify a cluster of one or more MigratoryData servers to which the NodeJS client will connect to using the API method MigratoryDataClient.setServers(). The NodeJS 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 NodeJS 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 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 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 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 the following 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. Also, handle the status notifications in your status handler defined above.