Subscribing to a JSON subject

The page provides an overview of how to subscribe to a subject of type JSON.

Contents:

Requirements
Overview
Example

Requirements

To use the JSON data type, your Caplin components and libraries must be at least as recent as the versions listed in the table below:

Product versions supporting the JSON data type
Product	Minimum Version
C DataSource API	7.1.9
Java DataSource API	7.1.9
.NET DataSource API	7.1.9
Liberator	7.1.8
Transformer	7.1.5
StreamLink iOS	7.1.0
StreamLink Android	7.1.1
StreamLink Java	7.1.1
StreamLink JS	7.1.1
StreamLink .NET	7.1.1

Overview

To subscribe to a JSON subject using StreamLink JS, follow the steps below:

Create one implementation of StreamLink’s JsonHandler interface to handle the realisation of JSON images and updates.

Example 1: a JsonHandler that applies a patch to a previously realised image

var jsonHandler = {
  parse: function (jsonString) {
    return JSON.parse(jsonString);
  },
  patch: function (existingObject, jsonPatchString) {
    var patch = JSON.parse(jsonPatchString);
    return patch.reduce(jsonpatch.applyReducer, existingObject); (1)
  },
  format: function () {}
};

1	The `jsonpatch` object is from the fast-json-patch library

Example 2: a JsonHandler that applies a patch by creating a new immutable state

var jsonHandler = {
  parse: function (jsonString) {
    return JSON.parse(jsonString);
  },
  patch: function (existingObject, jsonPatchString) {
    var patch = JSON.parse(jsonPatchString);
    var result = immer.produce(existingObject, function (existing) { (1)
      return patch.reduce(jsonpatch.applyReducer, existing); (2)
    });
    return result;
  },
  format: function () {}
};

1	The `immer` object is provided by the immer library
2	The `jsonpatch` object is provided by the fast-json-patch library

Specify your implementation of JsonHandler as the json_handler property of the configuration object when creating the StreamLink object:
```
var streamLink = caplin.streamlink.StreamLinkFactory.create({
  ...
  json_handler: jsonHandler
  ...
});
```
Implement the onJsonUpdate method in your implementation of SubscriptionListener. The method receives an event object of type JsonEvent. The JsonEvent.getJson() method returns a reference to the realised or patched JSON.
```
var subscriptionListener = {
  ...
  onJsonUpdate: function (subscription, event) {
    window.console.info(event.getJson());
  }
  ...
};
```

Subscribe to the JSON subject and connect

streamLink.subscribe("/EXAMPLES/JSON/AAPL", subscriptionListener);
streamLink.connect();

Example

The example below is adapted from the StreamLink JS examples that ship with Liberator. To view the example locally, activate your Liberator’s LiberatorWebsite and LiberatorDemoDataSource blades, and navigate to http://localhost:18080/docs/sljs/interactive/.

Code in the example that is specific to subscribing to JSON subjects is highlighted in yellow.

Example: subscribing to a JSON subject

<!DOCTYPE html>
<html>
  <head>
  <script src="//localhost:18080/sljs/streamlink.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fast-json-patch/2.0.7/fast-json-patch.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/immer@1.12.1/dist/immer.umd.js"></script>
  <link href="examplepage.css" type="text/css" rel="stylesheet"/>
</head>
<body onunload="streamLink.disconnect();">
  <pre id="recordLog"></pre>
  <pre id="displayLog">Log:</pre>

  <script>
    // Define how JSON messages are parsed and patched
    var jsonHandler = {
      parse: function (jsonString) {
        console.log("parse", jsonString);
        return JSON.parse(jsonString);
      },
      patch: function (existingObject, jsonPatchString) {
        console.log("patch", jsonPatchString, existingObject);
        var patch = JSON.parse(jsonPatchString);
        var result = immer.produce(existingObject, function (existing) {
          return patch.reduce(jsonpatch.applyReducer, existing);
        });
        console.log(jsonPatchString, JSON.stringify(result), null, "\t");
        return result;
      }
    };

    // Build the StreamLink object
    var streamLink = caplin.streamlink.StreamLinkFactory.create({
      username : "demouser",
      password : "demopass",
      liberator_urls: "rttp://localhost:18080",
      json_handler: jsonHandler
    });

    // Define the subscription listener.
    var subscriptionListener = {
      onSubscriptionStatus: function (subscription, event) {
        log(subscription.getSubject() + " is now " + event.getStatus());
      },
      onSubscriptionError: function (subscription, event) {
        log("Error: Subject " + subscription.getSubject() + " is " + event.getError());
      },
      onJsonUpdate: function (subscription, event) {
        render(event.getJson());
      }
    };

    function render(json) {
      document.getElementById("recordLog").innerHTML =
        "Subject: " + subject + "<br/>" + JSON.stringify(json, null, "\t");
    }

    function log(line) {
      document.getElementById("displayLog").innerHTML += "\n" + line;
    }

    // Subscribe to the record
    var subject = "/EXAMPLES/JSON/AAPL";
    streamLink.subscribe(subject, subscriptionListener);

    // Connect
    streamLink.connect();
  </script>
</body>
</html>

See also:

JSON data type