Interface Session

Example:

// Produce a fallback value stream for receiving JSON values.
var json = diffusion.datatypes.json();

session.addFallbackStream(json).on('value', function(topic, specification, newValue, oldValue) {
      console.log('New value ', newValue.get());
});

throws

an IllegalArgumentError if dataType is not a valid data type

This method will not cause the server to send any topic updates unless already subscribed. This allows the registration of listeners prior to subscribing via Session.select, or to add/remove listeners independently of subscriptions on the server.

The values as specific types, use the Streams will only receive values from topics for which the specified Data Type is compatible. Passing AnyDataType as second argument will create a polymorphic value stream that receives all data types. It is then up to the value handler to interpret the incoming data.

The first argument of this function can be a string, a TopicSelector, or a non-empty array of strings and TopicSelectors.

Example:

// Produce a value stream for receiving JSON values.
var json = diffusion.datatypes.json();

session.addStream(topic, json).on('value', function(topic, specification, newValue, oldValue) {
      console.log('New value ', newValue.get());
});

throws

an IllegalArgumentError if dataType is not a valid data type or if the selector could not be parsed

The returned request can be invoked with fetch. The server will evaluate the query and return a fetch result that provides the paths and types of the matching topics which the session has permission to read.

You will usually want to restrict the query to a subset of the topic tree, and to retrieve the topic values and/or properties. This is achieved by applying one or more of the fluent builder methods provided by FetchRequest to produce more refined requests.

Example:

// Create and send a fetch request. Then pass the results to a resultHandler
session.fetchRequest()
       .withValues(diffusion.datatypes.StringDataType)
       .fetch("*A/B//")
       .then(resultHandler);

see

diffusion.topics.FetchRequest

since

6.2

Example:

// Bind a single listener to the 'foo' event and then deregister it
var listener = function() {};
stream.on('foo', listener);
stream.off('foo', listener);

Example:

// Bind a listener to the 'foo' event and deregister all listeners
var listener = function() {};
stream.on('foo', listener);
stream.off('foo');

A single listener may be bound to an event by passing the event name and listener function.

Multiple listeners may be bound by passing in a CallbackMap, mapping event names to listener functions.

Example:

// Bind a single listener to the 'foo' event
stream.on('foo', function(arg1, arg2) {
    console.log("Called for 'foo' event", arg1, arg2);
});

Example:

// Bind multiple listeners
stream.on({
    foo : function() { ... },
    bar : function() { ... },
    baz : function() { ... }
});

Example:

session.pingServer().then(function(pingDetails) {
    console.log("Round-trip call to server took: " + pingDetails.rtt + " milliseconds");
});

Subscription causes the server to establish a subscription for this session to any topic that matches the specified selector, including topics that are added after the initial call to Session.select.

If the provided selector string does not begin with one of the prefixes defined by TopicSelectors, it will be treated as a direct topic path.

This function can take any number of arguments. Each argument can be a string or a TopicSelector. Alternatively, an array of strings and TopicSelectors can be passed as a single argument. At least one valid selector has to be specified.

The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the returned promise completes.

The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

Example:

// Subscribe to a topic foo
session.select("foo").then(function() {
    // Successfully subscribed
}, function(err) {
    // There was an error with subscribing to topic "foo"
});

throws

an IllegalArgumentError if the selector could not be parsed

No more updates will be received from the server for any topics matched by the selector. If no topics exist that match the selector, the server will do nothing.

Each topic that this session is unsubscribed from will cause an unsubscribe event. Any ValueStream objects produced from Session.addStream will remain open, and will continue to emit updates for topics that the session has not been unsubscribed from.

The returned result will resolve normally when the session has been unsubscribed. It will resolve with an error if the session is unable to unsubscribe, for instance due to security constraints.

This function can take any number of arguments. Each argument can be a string or a TopicSelector. Alternatively, an array of strings and TopicSelectors can be passed as a single argument. At least one valid selector has to be specified.

Example:

// Unsubscribe from a single topic
session.unsubscribe('foo');

Example:

// Unsubscribe from multiple topics
session.unsubscribe('?foo/.*');

throws

an IllegalArgumentError if the selector could not be parsed