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.
To directly specify the type of topic to create, provide a string path and a TopicType. Topics specified in this way are created with default topic properties, as described in TopicSpecification.
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.
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.
If the operation fails a 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
Example:
// Create a topic with a Topic Type
session.topics.add('foo/binary', diffusion.topics.TopicType.BINARY);
Example:
// 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);
Example:
// 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);
});
the topic path to create.
the topic type/specification
a Result for this operation
Register a MissingTopicHandler to handle requests for a branch of the topic tree.
The provided handler is called when a client subscribes using a topic selector that matches no existing topics. This allows a control client session to be notified when another session requests a topic that does not exist.
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.
a Result for this registration
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. At least one valid selector has to be specified.
Example:
// Remove the topic at 'foo/bar', leaving descendants
session.topics.remove('>foo/bar');
Example:
// Remove the topic at 'foo/bar' and all descendants
session.topics.remove('?foo/bar//');
the selector specifying the topics to remove
a Result resolving to a TopicRemovalResult
Register a deferred action to remove a branch of the topic tree when this session is closed.
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.
the path of the topic tree to remove
registration Result.
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;