Diffusion JavaScript API 6.1.5 Namespace: topics

Topic control feature.

Provides methods to change and update the topic tree stored on the server.

Example

// Get a reference to topic control feature
var topics = session.topics;

Methods

add(topicPath, specification, initialValue) → {Result.<Session.topics.TopicAddResult>}

Add a topic to the server at a specific path. This returns a Result.

The path should be a string. To express hierarchies, / can be used as a delimiter. This allows topics to be nested and grouped below each other. For example, session.topics.add('foo/bar'); creates the topic bar. A topic is not created at foo by this method.

Each topic has a particular type, which constrains the kind of values that the topic will allow. This type can either be explicitly provided, or included as part of a TopicSpecification.

Adding from topic type

To directly specify the type of topic to create, provide a string path and a diffusion.topics.TopicType. Topics specified in this way are created with default topic properties, as described in diffusion.topics.TopicSpecification.

Adding from topic specification

TopicSpecifications allows the creation of topics of a particular type, along with additional properties that determine how the topic operates. For instance, you may wish to specify that a topic will validate values before publishing, or that it will only publish values instead of deltas.

It is possible to provide an initial value to be used for the newly added topic. The provided value must be compatible with the specified topic type.

Operation results

If the topic was added, or a topic already exists with the same path and specification, the operation will succeed. If there is a problem with adding the topic then the result will be rejected with an error.

If any sessions have already subscribed to the same path that a topic is created for, they will receive a subscription event once the topic is added, and a value event with the initial value (if supplied).

If the session is closed when calling this method, the returned result will be rejected.

Failure

If the operation fails a diffusion.topics.TopicAddFailReason is provided. Adding a topic may fail because the session has insufficient permissions; a topic already exists at the specified path; or certain mandatory TopicSpecification properties were missing

Parameters:

Name	Type	Argument	Description
`topicPath`	String		The topic path to create.
`specification`	diffusion.topics.TopicType \| diffusion.topics.TopicSpecification	<optional>	The topic type/specification
`initialValue`	Object	<optional>	The initial topic value. As of 6.1, this is deprecated. In future versions, this initialValue will be removed completely.

Returns:

A Result.<Session.topics.TopicAddResult> for this operation

Type: Result.<Session.topics.TopicAddResult>

Examples

// Create a topic with a Topic Type
session.topics.add('foo/binary', diffusion.topics.TopicType.BINARY);

// Create a topic with a TopicSpecification
const TopicSpecification = diffusion.topics.TopicSpecification;
var specification = new TopicSpecification(diffusion.topics.TopicType.JSON, {
    TopicSpecification.VALIDATE_VALUES : "true"
});

session.topics.add('foo/json', specification);

// Handle the add topic result
session.topics.add('foo/bob', diffusion.topics.TopicType.JSON).then(function(result) {
    if (result.added) {
        console.log('Topic added');
    } else {
        console.log('A compatible topic already exists');
    }
}, function(error) {
    console.log('Topic add failed: ', error);
});

addMissingTopicHandler(topicPath, handler) → {Result.<undefined>}

The provided handler is called when a client subscribes or fetches using a topic selector that matches no existing topics. This allows a control client to intercede when another session requests a topic that does not exist. The control client may create the topic, perform some other action, or do nothing, before allowing the client operation to proceed by calling proceed(). Alternatively, the control client can call cancel() to discard the request.

A control client can register multiple handlers, but may only register a single handler for a given topic path. See MissingTopicHandler#onRegister. A handler will only be called for topic selectors with a path prefix that starts with or is equal to topicPath. If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

If the session is closed or the handler could not be registered, the returned Result will call its failure callback, and the handler's MissingTopicHandler#onClose or MissingTopicHandler#onError method will be called.

Parameters:

Name	Type	Description
`topicPath`	String	identifies a branch in the topic tree
`handler`	MissingTopicHandler	specifies the handler for the specified branch (unless overridden by a handler registered against a more specific branch)

Returns:

A Result.<undefined> for this registration

Type: Result.<undefined>

registerUpdateSource(path, updateHandler) → {Result.<undefined>}

Register a handler to provide exclusive updates for a particular branch of the topic tree. Once successfully registered, the handler will be called with lifecycle callbacks. This grants this session sole access to publish updates to topics at or under the branch used for registration.

If no other handlers have been registered for the topic path, the handler will enter the active state. This provides an updater which can then be used to publish updates for topics at or below the registered topic path.

If there is an existing handler for the topic path, the handler will be put into the standby state. This indicates that the handler is registered but does not have access to publish updates. Once all previously registered handlers are closed, this handler will transition to the active state.

The handler will be closed if the session closes or updater#close is called. This is a terminal state from which no further state transitions will occur. When a registered handler is closed, if there is another handler registered by a different session, this next handler will transition to an active state.

Handlers cannot be registered above or below the topic path of any other registered handlers. Attempting to do so will close the handler.

Parameters:

Name	Type	Description
`path`	String	The topic path to register an update source for.
`updateHandler`	TopicUpdateHandler	handler specifies the handler for the specified branch (unless overridden by a handler registered against a more specific branch)

Returns:

a Result.<undefined> for this operation

Type: Result.<undefined>

Examples

session.topics.registerUpdateSource('foo/bar', {
    onRegister : function(topicPath, unregister) {
        // The handler has been registered

        // Unregister the handler
        unregister();
    },
    onActive : function(topicPath, updater) {
        // Now that we're active, we have sole write access for all topics under 'foo/bar'
        updater.update('foo/bar/baz', 123).then(function() {
              // Updates return a promise just like session.topics#update
        });
    },
    onStandby : function(topicPath) {
        // The updater is registered, but another updater currently holds the active state.
    },
    onClose : function(topicPath) {
       // The updater is closed
    }
});

// 'client' is an anonymous session that has insufficient permission to register an update source
client.topics.registerUpdateSource('foo/bar', {
    onRegister : function(topicPath, unregister) {
    },
    onActive : function(topicPath, updater) {
    },
    onStandby : function(topicPath) {
    },
    onClose : function(topicPath, error) {
       // The updater is closed because the error is diffusion.errors.ACCESS_DENIED
    }
});

remove(path) → {Result.<undefined>}

Remove a topic from the server at a specific path.

If there are any topics below the path being removed, they will also be removed.

For every topic that is removed, an unsubscribe event will be fired for each session subscribed to that topic.

Topics may also be automatically removed according to removal criteria specified using the diffusion.topics.TopicSpecification.REMOVAL topic property.

In future versions of Diffusion, this method will be changed to behave in the same manner that Session.topics#removeSelector currently does.

Parameters:

Name	Type	Description
`path`	String	The topic path to remove

Returns:

A Result.<undefined> for this operation

Type: Result.<undefined>

Examples

// Remove the topic at 'foo/bar'
 session.topics.remove('foo/bar');

// Remove all topics under 'foo'
session.topics.remove('foo').then(function() {
    // Successfully removed
}, function(err) {
    // There was an error removing the topic
});

removeSelector(selector) → {Result.<undefined>}

Remove one or more topics at the server.

The topics to remove will depend upon the nature of the topic selector specified. If the selector does not have descendant pattern qualifiers (i.e. / or //), only those topics that exist at paths indicated by the selector will be removed and not their descendants. If a single / qualifier is specified, all descendants of the matching topic paths will be removed. If // is specified, all branches of the topic tree that match the selector (i.e topics at the selected paths and all descendants of the selected paths) will be removed.

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.

Deprecated since 5.9. This method will removed in future versions of Diffusion, with equivalent functionality to be provided by Session.topics#remove.

Parameters:

Name	Type	Description
`selector`	String \| TopicSelector \| Array.<String>	The selector specifying the topics to remove

Since:

Returns:

A Result.<undefined> for this operation

Type: Result.<undefined>

Examples

// Remove the topic at 'foo/bar', leaving descendants
session.topics.removeSelector('>foo/bar');

// Remove the topic at 'foo/bar' and all descendants
session.topics.removeSelector('?foo/bar//');

removeWithSession(topicPath) → {Result.<Session.topics.RemoveWithSessionResult>}

A removal action can be registered at any point in the topic tree, but can not be placed above or below existing registrations. An error event will be emitted if the server rejects the registration.

When this session is closed, regardless of reason, this topic and all topics below it will be removed from the topic tree.

Multiple sessions can request that the same branch be removed. If a branch has multiple registrations, then the marked topics will not be removed until all registered sessions have been closed.

When registration is successful, the Result will call the success callback with an object representing the registration with the property function deregister that can be called at any point to remove this registered action. The deregistration function returns a new Result.

If the session is closed when calling this method, the returned result will emit an error event.

Deprecated since 6.1

The preferred method for automatic removal of topics is the REMOVAL topic property. To achieve the equivalent of this method the property can be specified as:-

when this session closes remove "?topicPath//"

To achieve a dependency upon more than one session, a condition specifying a principal name or some other session property can be used.

This method will be removed in a future release.

Parameters:

Name	Type	Description
`topicPath`	String	The path of the topic tree to remove

Returns:

Registration Result.<Session.topics.RemoveWithSessionResult>.

Type: Result.<Session.topics.RemoveWithSessionResult>

Example

// Remove all topics under 'foo'
session.topics.removeWithSession('foo').then(
    function(registration) {
        // Registration complete

        // Deregister this action
        registration.deregister().then(
            function() {
                // Deregistration complete
            },
            function(err) {
                // Failure while deregistering
            }
        );
    },
    function(err) {
        // Could not register
    }
);

update(path, value) → {Result.<String>}

Update a topic on the server with a new supplied value. The returned Result will complete if the update is successfully applied, and any sessions subscribed to the same topic will be notified of the new topic value.

If the session is closed when calling this method, the returned result will also emit an error event.

Failure

If the operation fails a UpdateFailReason is provided. The value provided must be compatible with the data type of the topic being updated, or the update will be rejected. Updates will also be rejected if the session has insufficient permissions, or the topic does not exist.

Prefer Session.topics#updateValue when updating a Double or Int64 topic. This method can infer the wrong data type when updating a Double topic with a value that does not have a fractional component.

Parameters:

Name	Type	Description
`path`	String	The topic path to update
`value`	Object	The value to update the topic with

Returns:

A Result.<String> for this operation. The value is the topic path that has been updated.

Type: Result.<String>

Examples

// Update topic 'foo/bar' with string value.
session.topics.update('foo/bar', 'baz');

// Update topic with JSON content
var content = diffusion.datatypes.json().from({ "foo" : "bar" });

session.topics.update('foo/bar', content);

updateValue(path, value, datatype) → {Result.<String>}

This method is similar to Session.topics#update but takes in a data type so that the updater can determine which data type to use when encoding the value.

Note that if a double value is applied to an Int64 topic, the fractional component is ignored. Updating a topic with a different value type can lead to an unexpected value getting applied to the topic.

Parameters:

Name	Type	Description
`path`	String	The topic path to update
`value`	Object	The value to update the topic with
`datatype`	DataType	The data type to be used for encoding the value

Returns:

A Result.<String> for this operation. The value is the topic path that has been updated.

Type: Result.<String>

Example

session.topics.updateValue('foo', 123.45, diffusion.datatypes.double());

Type Definitions

RemoveWithSessionResult

Type:

Object

Properties:

Name	Type	Description
`deregister`	function	function to remove this registered action

TopicAddResult

Type:

Object

Properties:

Name	Type	Description
`added`	Boolean	whether the Topic was added or not
`topic`	String	the Topic path that was used