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 plain HTTP connection to send and receive, 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.

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 on 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 using a subscription. Subscriptions allow the session to select a particular topic, and register a function to handle notifications that a topic's data has been changed. A session may subscribe to many topics, as well as subscribe to the same topic multiple times.

The simplest way to subscribe is

var subscription = session.subscribe('topic/foo');

The subscription that is returned is a stream of update events containing values encoded as binary Buffer objects that can be transformed as appropriate. When the value of any of the selected topics changes. These events can be listened to like so:

subscription.on('update', function(value, topic) {
    // Do something with the value
});

For anything other than simple topic types it is more convenient to type the stream of values so that they can be accessed without requiring decoding. These values are then delivered as value events. So, for instance, to subscribe to a stream of JSON updates:

  subscription.asType(diffusion.datatypes.json()).on('value', function(topic, specification, value) {
      var jsonvalue = value.get(); // Do something with the new JSON value
  });

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

Because clients will most likely consume data in a more specific type, subscriptions to update events can be transformed. Calling the transform method will return a new subscription stream with a bound transformation function. This will be applied to all topic values before being passed to user listeners.

session.subscribe('topic/foo').transform(String).on('update', function(update) {
    // Receive the same data, parsed into a String object
});

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.

Receive data from topics

• Subscribe to JSON or binary topics.
  Use the session.subscribe method to subscribe to a topic and get a Subscription object that you can use to receive updates and subscription events.
  The updates to a JSON or binary topic can be interacted with by the classes in the diffusion.datatypes namespace. Call asType method on your Subscription object to get a TypedSubscription that receives the values as a particular datatype.

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

• Subscribe to other topic types.
  Use the session.subscribe method to subscribe to a topic and get a Subscription object that you can use to receive updates and subscription events.
  The updates to record topics can be interacted with by the classes in the diffusion.metadata namespace.

Create and manage topics

• Add a topic.
  Use the add method to add a topic. Depending on the parameters you pass to the method, you can create a topic from an initial value, by explicitly defining the topic type, or by providing metadata.

• 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 deleted when the client session closes with the removeWithSession method.

Update topics

• Update a topic non-exclusively by using the update method.

• Update a topic exclusively.
  Use the registerUpdateSource method to register a TopicUpdateHandler to perform updates on a topic.

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

• Update other topic types by using the classes in the diffusion.metadata namespace to create update values.

Manage other clients

• Subscribe other client sessions to topics.
  Use the subscribe and unsubscribe methods in Session.clients namespace 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

• 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 listen method to receive messages sent to this client session through a MessageStream.

• Receive messages sent to a path.
  Use the addHandler method to register a MessageHandler that receives messages sent to a path.

Authenticating clients

The server 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

• 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 updateAuthenticationStore method to update the system authentication store.