Subscribing to a JSON subject

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

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:

  1. 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
  2. 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
      ...
    });
  3. 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());
      }
      ...
    };
  4. 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: