Updating topics
A client can use the TopicUpdateControl feature to update topics.
- 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.
- 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:
,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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- The topic does not already have an active update source registered against it
- The client has the 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, Int64, String, Double, RecordV2. When a topic is updated with a value updater, the value is cached. Subsequent updates can use the cached value to calculate a delta of change between the two values and just send that to the Diffusion server, thus reducing the data volume to the Diffusion server. |
Updater | Use an updater to update one of the following topic types: single value, record, stateless. |
Using a value updater to stream values through topics
Required permissions:
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.
- 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:
- 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 Diffusion 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: 2018/04/06