Expand Collapse
Just a second...

Updating topics

A client can use the TopicUpdateControl feature to update topics.

A client can update a topic in one of the following ways:
Exclusive updating

By registering with the Diffusion™ server as an update source for the branch of the topic tree that contains the topic to be updated.

If a client is registered as the active update source for a branch of the topic tree, no other clients can update topics in that branch of the topic tree.

You must use an exclusive update source with a value updater to benefit from delta updating.

Non-exclusive updating
By getting a non-exclusive updater from the TopicUpdateControl feature. This updater can be used to update any topic that does not already have an active update source registered against it.

Registering as an exclusive update source

Required permissions: update_topic, register_handler

A client must register as an update source for a branch of the topic tree to be able to exclusively publish content to topics in that branch. This locks the branch of the topic tree and prevents other clients from publishing updates to topics in the branch.

When a client registers as an update source the following events occur:
  1. The client requests to register as an update source on a branch of the topic tree.
    • The update source is registered against a topic path. This is a path that identifies a branch of the topic tree, for example foo/bar. The update source is registered as a source for that branch of the topic tree, for example the topics foo/bar/baz and foo/bar/fred/qux are included in the specified branch of the topic tree.
    • You cannot register an update source above or below an existing update source. For example, if a client has registered an update source against foo/bar/fred another client cannot register an update source against foo/bar or foo/bar/fred/qux.
    • You can register an update source against a topic owned by an existing publisher or a topic that has an update source created by the server that is used for topic failover.
  2. The server validates the registration request and returns one of the following responses:
    • If the request is valid, the Diffusion server calls the OnRegister callback of the update source and passes a RegisteredHandler that you can use to deregister the update source.
    • If the request is not valid, the Diffusion server calls the onClose callback of the update source.

      For example, a registration request is not valid if it registers against a topic branch that is above or below a branch where an existing update source is registered.

  3. When the update source is registered, the Diffusion server calls one of the following callbacks:
    • If the update source is the primary update source, the Diffusion server calls the onActive callback of the update source.
    • If another update source is already the primary source for this branch of the topic tree, the Diffusion server calls the onStandby callback of the update source.
  4. If an update source is on standby, the update source cannot update the topics it is registered against. If the active update source for a branch of the topic tree closes or becomes inactive, a standby update source can then become active and become the primary update source for that branch of the topic tree.
  5. If an update source is active, the Diffusion server provides the update source with an Updater. The update source can use the Updater to update the topics it is registered against.
  6. If an active update source exists for a branch of the topic tree, no other clients can update topics in that branch of the topic tree.

Updating a topic non-exclusively

Required permissions: update_topic

To non-exclusively update topics, a client must get a non-exclusive updater from the TopicUpdateControl feature. This updater can be used to update any topic under the following conditions:
  • The topic does not already have an active update source registered against it
  • The client has the update_topic permission for the topic

Types of updater

Updater type Description
Value updater Use a value updater to update one of the following topic types: JSON, binary. In future releases, more topic types will use the value updaters.

If you are using an exclusive update source, a value updater can calculate the delta of change between two values and send only that to the Diffusion server, reducing the data volume.

Updater Use an updater to update one of the following topic types: single value, record, stateless, custom, protocol buffer, paged.

Using a value updater to stream values through topics

Required permissions: update_topic

A client uses a value updater to publish a value to a topic. Value updaters are typed and can only be used to update topics whose data type matches the data type of the value updater.

Value updaters can be used for exclusive or non-exclusive updating, depending on how the value updater is acquired.

When used exclusively, value updaters cache the values that are passed to them. When a value is passed to a value updater, the value updater compared that value with the previously cached value. If it is more efficient to do so, the value updater publishes a delta of changes between the previous value and the new value instead of publishing the full new value.

For non-exclusive updating, the complete value is always sent to the server and the value is not cached.

When the client uses a value updater method to publish values, it passes in the following parameters:
Topic path
The path to the topic to be updated.

If the value updater is an exclusive updater, this topic must be in the branch of the topic tree that the client is the active update source for and that the updater is associated with.

Value

The value to use to update the topic. This value is of the data type that matches the data type of the topic being updated.

Context
OPTIONAL: A context object can be passed in to the update method that provides application state information.
Callback
The server uses the callback to return the result of the update. If the update completes successfully, the Diffusion server calls the callback's onComplete method. Otherwise, the Diffusion server calls the callback's onError method.

Using an updater to publish content to topics

Required permissions: update_topic

A client uses an updater to publish content to topics. Updaters can be used for exclusive or non-exclusive updating, depending on how the updater is acquired. When the client uses an updater method to publish content, it passes in the following parameters:
Topic path
The path to the topic to be updated.

If the updater is an exclusive updater, this topic must be in the branch of the topic tree that the client is the active update source for and that the updater is associated with.

Content

The information about the update can be provided as either a simple Content object or as a more complex Update object.

The content that is to be published to the topic. The client must use the appropriate content type when formatting the content. If the content uses the wrong content type for the topic, it can cause an error.

Update

The information about the update can be provided as either a simple Content object or as a more complex Update object.

An update that contains the content that is to be published to the topic and other information about the update, such as its type.

Use the Builder methods provided in the Unified API to build your Update objects.

Context
OPTIONAL: A context object can be passed in to the update method that provides application state information.
Callback
The server uses the callback to return the result of the update. If the update completes successfully, the Diffusion server calls the callback's onComplete method. Otherwise, the Diffusion server calls the callback's onError method.

This page last modified: 2017/08/17