diffusion

Diffusion JavaScript API

The Diffusion JavaScript API allows interaction with a Diffusion server from both the browser and Node.js.

Clients use a WebSocket or HTTP connection to send and receive data, as well as perform other functions such as adding, removing or updating topics. For a full list of capabilities in the JavaScript API, see the Contents section below.

Installing

Install the client using npm install diffusion --save

Pre-bundled browser artifacts are included in node_modules/diffusion/dist

To import Diffusion use either require or ES6 style syntax

require

var diffusion = require('diffusion');

ES6

import * as diffusion from 'diffusion';

Browser Bundles

Browser bundles can be found in the dist folder located in the package root.

• When installing via npm, the bundles are located in node_modules/diffusion/dist/.
• In the on-premise installation of Diffusion, they can be found in the clients/js/ folder.
• When unpacking the diffusion-js-x.y.z.tgz, they are extracted to the package/dist/ folder.
• They can also be downloaded directly from the Diffusion release pages

The bundles are organized into the following files:

diffusion.js: The complete diffusion client including all features. It exposes the diffusion object as a global variable.

diffusion-worker.js: A script that can be loaded into a shared worker. The location of this script can be passed to diffusion.connectShared() to create sessions that are shared across browser tabs.

modular/diffusion-core.js: The core bundle of the modular client. Just like the diffusion.js package, this exposes the diffusion object in the global context. Sessions created from this package will lack any features except value streams and topic subscription. Attempting to access a feature that hasn't yet been loaded into the browser will result in an Error being thrown. Additional features can be loaded dynamically after a session has been created. Features will be available to all sessions once the respective feature bundle has been loaded into the browser.

modular/diffusion-feature-XYZ.js: The bundle for the feature XYZ. These bundles can be loaded into the browser dynamically after the core bundle of the modular client. Each bundle will provide an additional feature to the client. The following bundles are available.

• diffusion-feature-client-control.js: Client Control Feature
• diffusion-feature-messages.js: Request Response Messaging Feature
• diffusion-feature-remote-servers.js: Remote Servers Feature
• diffusion-feature-security.js: Security Feature
• diffusion-feature-session-lock.js: Session Locks Feature
• diffusion-feature-time-series.js: Time Series Feature
• diffusion-feature-topic-control.js: Topic Control Feature
• diffusion-feature-topic-notifications.js: Topic Notifications Feature
• diffusion-feature-topic-update.js: Topic Update Feature
• diffusion-feature-topic-views.js: Topic Views Feature

A feature can be loaded into the browser by dynamically creating a <script> element and setting the src attribute.

// create a new script element
const script = document.createElement('script');

// set the src attribute to the path of the module bundle
script.src = 'path_to_library/diffusion-feature-topic-update.js';

script.onload = function () {
    // the Topic Update feature is now available on all future and existing
    // sessions
};

// add the script to the document to ensure loading
document.head.appendChild(script);

TypeScript

The Diffusion package includes TypeScript bindings, specified in node_modules/diffusion/typescript

The diffusion object

The documentation will frequently refer to the diffusion object. Technically, this is the module object that is obtained when importing the Diffusion library using one of the methods described above. The diffusion object exposes a number of global constants and functions.

When using one of the pre-bundled packages in the browser, the diffusion object will be attached to the global windows object.

Constants

version: string;
The version of this client library in the form major.minor.patch

build: string
The build version of this client library

Functions

function log(level: LogLevel | keyof typeof LogLevel)
Set the level of logging used by Diffusion.

function connect(options: Options): Result<Session>
Connect to a specified Diffusion server.

function escape(s: string)
Escapes special characters in a string that is to be used within a topic property or a session filter.

function stringToRoles(s: string)
Utility method which converts a string of the format required by the $Roles session property into a mutable set of strings.

rolesToString(roles: Set<string> | string[])
Utility method which converts a set of authorization roles to the string format required by the $Roles session property.

function updateConstraints(): UpdateConstraintFactory
Returns an update constraint factory.

Namespaces

const datatypes
Access to the datatypes namespace

const locks
Access to the locks namespace

const selectors
Access to the selectors namespace

const topics
Access to the topics namespace

const topicUpdate
Access to the topicUpdate namespace

const errors
The ErrorReason enum

const clients
Access to PropertyKeys and other client control options

Quick start

A client Session maintains a connection to the server. To create a session, simply do

 diffusion.connect('diffusion.example.com');

It is also possible to connect with a map of options

diffusion.connect({
   host : 'diffusion.example.com',
   port : 8080,
   secure : false,
   principal : 'admin',
   credentials : 'password'
});

Connecting returns a Promise - this will succeed if the session could be connected, or fail if not.

diffusion.connect('diffusion.example.com').then(function(session) {
    // Connected!
}, function(error) {
    // Failed to connect :(
});

Sessions emit events to indicate their status such as when they are disconnected or closed. These events are easy to listen to:

session.on('disconnect', function(reason) {
    // Lost connection to the server!
});

session.on('close', function() {
    // Session is closed!
});

Once a session is closed, it can never be re-opened.

Subscriptions

Data in Diffusion is distributed via topics. A topic has state, which can be updated. The state can be simple - such as a string or an integer - or more complex - such as a JSON document. Each topic has a unique path and is addressed through a topic selector.

The way that a session receives data is by subscribing. Subscriptions allow the session to select one or more topics to receive values from. A session may subscribe to many topics, as well as subscribe to the same topic multiple times.

session.select('topic/foo')

To attach listeners for received values, a ValueStream is used. The stream that is returned will emit value events when the value of the selected topic changes.

session.addStream('topic/foo', diffusion.datatypes.json()).on('value', function(topic, specification, newValue, oldValue) {
    // Do something with the value
    var value = newValue.get();
});

It is possible to register any number of streams to a subscription's events. They will each be called when a new value is received.

Contents

The JavaScript client provides namespaces, classes, and methods that support the following capabilities:

Basics

• Connect the JavaScript client to Diffusion or Diffusion Cloud by using the diffusion.connect method.

• To change the security principal that the client is connected with, use the changePrincipal method.

• The client can log out information by using the diffusion.log method.

• The client can check its connectivity and roundtrip time to the server by using the pingServer method.

Receive data from topics

• Subscribe to topics. Use the session.select method to subscribe to a topic. The updates to a topic can be interacted with by registering a ValueStream and a provided datatype to start receiving the values of that datatype.

• Fetch data from topics. Use the fetch method to make a fetch request and get a FetchResult object that you can use to receive fetched values.

Create and manage topics

Creating and managing topics is handled through the topics feature.

• Add a topic. Use the add method to add a topic. You can create a topic by explicitly defining the topic type, or by providing a TopicSpecification with optional properties.

• Handle missing topics. Use the addMissingTopicHandler method to register a MissingTopicHandler. This handler receives a MissingTopicNotification when a client session subscribes to a topic that does not currently exist. The notified client can then choose to create that topic if appropriate.

• Remove topics. Use the remove method to remove topics. You can also mark topics to be removed automatically with the TopicSpecification property REMOVAL.

Update topics

Updating topics is handled through the topicUpdate feature.

• Update a topic using the set method.

• Create an update stream for creating and updating a specific topic using the createUpdateStream

• Update topics by using the classes in the diffusion.datatypes namespace to create update values.

Manage other clients

Updating topics is handled through the clients feature.

• Subscribe other client sessions to topics. Use the subscribe and unsubscribe methods to manage another client session's subscriptions.

• Receive notifications about other sessions and their properties. Use the setSessionPropertiesListener method to register a SessionPropertiesListener to receive notifications for session events or when a session changes properties.

• Query the session properties of a specific session. Use the getSessionProperties method. Specify which sets of properties to receive using PropertyKeys.

Send messages

Sending and receiving messages is handled through the messages feature.

• Send a message. Use the send method to either send a message to a specific client session or send a message to a path.

• Receive messages sent to this client session. Use the setRequestStream method to receive messages sent to this client session through a RequestStream.

• Receive messages sent to a path. Use the addRequestHandler method to register a RequestHandler that receives messages sent to a path.

Authenticating clients

Authenticating clients and modifying the authentication store is handled through the security feature.

• Register an authentication handler to authenticate other client sessions. Implement an Authenticator and use the setAuthenticator method to register it with the server.

The server also uses information stored in the system authentication store to authenticate connecting clients.

• Get the system authentication store information with the getSystemAuthenticationConfiguration method.

• Update the system authentication store. Use the authenticationScriptBuilder method to get a SystemAuthenticationScriptBuilder. The builder can be used to create a script. Pass the script to the updateAuthenticationStore method to update the system authentication store.

Updating security roles

The security feature also allows querying and updating a session's security roles.

• Get the security store information getSecurityConfiguration method.

• Update the security store. Use the securityScriptBuilder method to get a SecurityScriptBuilder. The builder can be used to create a script. Pass the script to the updateSecurityStore method to update the system authentication store.