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, as well as perform other functions such as adding, removing or updating topics.

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 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 FetchStream object that you can use to receive fetched values.

Create and manage topics

• 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

• 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 topics by using the classes in the diffusion.datatypes namespace to create update values.

Manage other clients

• Subscribe other client sessions to topics.
  Use the select 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 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

• Register an authentication handler to authenticate other client sessions.
  Implement an AuthenticationHandler and use the setAuthenticationHandler 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

• 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.