Namespace: topics

diffusion. topics

Classes

TopicSpecification

Members

<static, readonly> TopicAddFailReason

The reason that a topic could not be added.
Properties:
Name Type Default Description
EXISTS The topic already exists with the same details.
EXISTS_MISMATCH The topic already exists, with different details.
INVALID_PATH The topic path is invalid.
INVALID_DETAILS The topic details are invalid.
USER_CODE_ERROR A user supplied class could not be found or instantiated.
TOPIC_NOT_FOUND A referenced topic could not be found.
PERMISSIONS_FAILURE Invalid permissions to add a topic at the specified path.
INITIALISE_ERROR The topic could not be initialised, supplied value may be of the wrong format.

Deprecation notice

This value is associated only with deprecated methods that allow the specification of an initial value when creating a topic. It will be removed in a future release.

UNEXPECTED_ERROR An unexpected error occured while creating the topic.
CLUSTER_REPARTITION When trying to create the topic the cluster was migrating the partition that owns the topic. The correct owner could not be identified and the request failed. This is a transient failure for the duration of the partition migration.
EXCEEDED_LICENSE_LIMIT Adding the topic failed because of a license limit.
INCOMPATIBLE_PARENT Adding the topic failed because a topic owned by a publisher is already bound to the parent path.
INCOMPATIBLE_MASTER Adding a slave topic failed because a topic owned by a publisher is already bound to the specified master path.
EXISTS_INCOMPATIBLE Adding the topic failed because a topic is already bound to the specified path but the caller does not have the rights to manage it.

This can be because the topic is being managed by a component with exclusive control over the topic, such as fan-out or a publisher and thus the caller will not be able to update or remove the topic.

If the caller has suitable permissions then it could still subscribe to the topic, but the topic's specification may be different from that requested.

INVALID_NAME The supplied topic path is invalid.
Example
session.topics.add("foo").then(function() { ... }, function(err) {
    switch (err) {
         case diffusion.topics.TopicAddFailReason.EXISTS:
             ...
         case diffusion.topics.TopicAddFailReason.INVALID_PATH:
             ...
    }
});

<static, readonly> TopicType

Enum containing possible Topic Types.
Properties:
Name Type Default Description
STATELESS Stateless Topic.

A stateless topic is one that has no data maintained at the server and performs no specific function. Such a topic would normally be used simply to act as an organisational node within the topic tree but may also be used for sending messages.

Deprecation notice

This topic type has been deprecated, and will be removed in a future release.

Instead use a topic type that supports the DONT_RETAIN_VALUE property, and set the property to "true".

SINGLE_VALUE Single value topic.

This is a stateful topic that maintains its state as a single String value which may optionally be validated and constrained by type (e.g diffusion.metadata.Integer, diffusion.metadata.Decimal). The type is defined by a diffusion.metadata instance.

Subscribing to SINGLE_VALUE topics is more involved than subscribing to other topic types. SINGLE_VALUE topics can only be subscribed to in binary format, leaving the application with the job of decoding the String data.

Unless interoperability with an existing Diffusion Publisher implementation is required, one of STRING, INT64, DOUBLE, or BINARY may be better suited.

RECORD Record topic.

This is a stateful topic that maintains its state in record format. The format of the topic content may be one or more Records as defined by an item of diffusion.metadata.MRecordContent metadata. When such a topic is updated, the metadata is used to interpet the data and make comparisons between the current topic state and the update such that a delta of change can be calculated for publishing to subscribed clients.

This topic type has now been deprecated and will be removed in a future release. RECORD_V2 is the preferred alternative.

SLAVE Slave Topic.

A topic that references another topic (the master topic) which has data (i.e. an alias). It effectively allows a topic's data to be shared across more than one topic node.

A client cannot tell that it is subscribed to a slave topic. A client requesting details of a slave topic will receive the details of the master topic. A client subscribing to the slave topic will receive all updates to the master topic. The slave topic itself may not be updated.

Any number of slave topics may reference the same master topic.

If a topic is removed that referenced by slave topics, all such slave topics are also automatically removed.

Slave topics are unable to be created by the Javascript client, but may safely be subscribed to.

ROUTING Routing Topic.

A functional topic that can point to different target topics for different clients.

From the point of view of a client subscribing to such a topic this would be seen as a normal stateful topic but it has no state of its own and cannot be published to.

Such a topic may specify a user written Java class which will be invoked to define the mapping of the topic to another data topic when a client subscribes. Alternatively the mapping can be delegated to a control client using the SubscriptionControl feature.

BINARY Binary Topic.

This is a stateful topic that handles data in Binary format.

JSON JSON (JavaScript Object Notation) Topic.

This is a stateful topic that handles data in JSON representation.

STRING Topic that stores and publishes String values. Based on the string data type.

Supports null String values.

Supports delta-streams.

INT64 Topic that stores and publishes 64-bit integer values. Based on the int64 data type. Values are of the type diffusion.datatypes.Int64.

Supports null int64 values.

Does not support delta-streams - only complete values are transmitted.

DOUBLE Topic that stores and publishes IEEE 754 double-precision floating point numbers (i.e native JavaScript Numbers). Based on the double data type.

Supports null Double values.

The topic does not support delta-streams - only complete values are transmitted.

TIME_SERIES Time Series Topic.

A time series is a sequence of events. Each event contains a value and has server-assigned metadata comprised of a sequence number, timestamp, and author.

A time series topic allows sessions to access a time series that is maintained by the server. A time series topic has an associated event data type, such as Binary, String, or JSON, that determines the type of value associated with each event.

Retained range

The TIME_SERIES_SUBSCRIPTION_RANGE property configures the range of historic events retained by a time series topic. If the property is not specified, a time series topic will retain the ten most recent events.

Subscription range

The TIME_SERIES_SUBSCRIPTION_RANGE property configures a time series topic to send a range of historic events from the end of the time series to new subscribers. This is a convenient way to synchronize new subscribers without requiring the use of a range query.

By default, new subscribers will be sent the latest event if delta streams are enabled and no events if delta streams are disabled. See the description of Subscription range in the Session.timeseries time series feature} documentation.

Mandatory properties

The TIME_SERIES_EVENT_VALUE_TYPE property must be provided when creating a time series topic.

RECORD_V2 Topic that stores and publishes data in the form of records and fields. Based on the RecordV2 data type.

Supports delta-streams.

Example
// Get a topic type for adding topics
var topicType = diffusion.topics.TopicType.JSON;

session.topics.add("foo", topicType);

<static, readonly> UnsubscribeReason

Enum containing reasons that an unsubscription occurred.
Properties:
Name Type Default Description
SUBSCRIPTION_REFRESH The server has re-subscribed this session to the topic. Existing streams are unsubscribed because the topic type and other attributes may have changed.

This can happen if a set of servers are configured to use session replication, and the session connected to one server reconnects ("fails over") to a different server.

A stream that receives an unsubscription notification with this reason will also receive a subscription notification with the new TopicSpecification or TopicDetails.

STREAM_CHANGE A fallback stream has been unsubscribed or subscribed due to the addition or removal of a stream that selects the topic.
REQUESTED The unsubscription was requested by this client.
CONTROL The server or another client unsubscribed this client.
REMOVED The topic was removed
AUTHORIZATION The unsubscription occurred because the session is no longer authorized to access the topic.
Example
// Use UnsubscribeReason to validate unsubscription notifications
session.subscribe(">foo").on('unsubscribe', function(reason, topic) {
    switch (reason) {
        case diffusion.topics.UnsubscribeReason.REMOVED :
            // Do something if the topic was removed
        default :
            // Do something else if the client was explicitly unsubscribed
    }
});

<static, readonly> UpdateFailReason

The reason that a topic could not be updated.
Properties:
Name Type Default Description
INCOMPATIBLE_UPDATE The update was of a type that is not compatible with the topic it was submitted for, or the topic does not support updating.
UPDATE_FAILED The update failed, possibly because the content sent with the update was invalid/incompatible with topic type or data format.
INVALID_UPDATER The updater used is not active.
MISSING_TOPIC The topic being updated does not exist.
INVALID_ADDRESS Invalid key or index used for addressing topic content.
DUPLICATES Violation of content duplication restrictions.
EXCLUSIVE_UPDATER_CONFLICT Attempt to perform a non-exclusive update to a topic branch that already has an update source registered to it.
DELTA_WITHOUT_VALUE An attempt has been made to apply a delta to a topic that has not yet has a value specified for it.
CLUSTER_REPARTITION An update to a replicated topic failed because the cluster was repartitioning due to a server starting, stopping, or failing. The session can retry the operation.
INCOMPATIBLE_STATE An update could not be performed because the topic is managed by a component (e.g fan-out) that prohibits updates from the caller.
Example
session.topics.update("foo", "bar").then(function() { ... }, function(err) {
    switch (err) {
        case diffusion.topics.UpdateFailReason.MISSING_TOPIC:
            ...
        case diffusion.topics.UpdateFailReason.EXCLUSIVE_UPDATER_CONFLICT:
            ...
    }
});