In order to update any topic the client must have suitable permissions for that topic.

A client does not have to be subscribed to a topic in order to update it.

Topics may be updated exclusively or non-exclusively. In exclusive mode the client registers as the update source for a particular branch of the topic tree and once registered no other client will be able to update topics in that branch. In non-exclusive mode a client may update any topic as long as there is no exclusive update source for its branch.

In either mode an TopicUpdateControl.Updater is needed to send the updates. The way in which the updater is obtained is dependent upon the mode (see below).

Any topic type may be updated using the updater directly (see "Direct updating" below) but when exclusive updating, the preferred mechanism is to use "Value updating" (see below) where the latest value sent to the server is cached locally so that deltas can automatically be calculated and sent for subsequent updates. Note that the two types of updating must never be mixed for any single topic otherwise results could be unpredictable. Value updating may also be used for non-exclusive updating but complete values will always be sent and values will not be cached.

Updaters are thread-safe, but do not update topics from different threads as order can not be guaranteed.

Exclusive updating

The client updates topics by registering itself as a source for a branch of the topic tree using registerUpdateSource.

The server will determine if the source may be registered, and if so, whether it is in an active or standby mode. The default registration behavior is that multiple sources may register on the same topic path, but may not register above or below existing sources on the same branch. Only one topic source will be active for a given topic path, with others being set to standby. When the currently active topic source is de-registered, the server will promote one of the other sources to an active state.

If registration succeeds, onRegistered will be called with a Registration instance. The close method of the registration can later be called to deregister the source.

When the source becomes active it will be notified via the onActive method which provides an TopicUpdateControl.Updater which can be used to send updates.

Non-exclusive updating

The client can perform non-exclusive updates using an updater obtained from the updater() method. This updater may be used to send updates to any topic that the client has permission to update. However, such updates will fail if there is already a registered update source for the topic.

If more than one client sends non-exclusive updates to the same topic, the updates are performed on a last update wins basis.

Value updating

The preferred mechanism for the updating of DataType based topics (for example, JSON) is using a TopicUpdateControl.ValueUpdater.

A value updater is obtained from the TopicUpdateControl.Updater using the TopicUpdateControl.Updater.valueUpdater(Class) method. The class specified will indicate which topic types may be updated using the updater (so for TopicType.JSON specify JSON.class).

The topic is updated by simply using the TopicUpdateControl.ValueUpdater.update(java.lang.String, V, com.pushtechnology.diffusion.client.features.control.topics.TopicUpdateControl.Updater.UpdateCallback) method to specify a new value.

For exclusive updating, when a value is specified in this way it is cached so that for subsequent update calls the updater can calculate a delta of change between the two values and just send that to the server, thus reducing the data volume to the server. Cache values are kept for the duration of the registration but there are cache management methods on the updater that allow cache entries to be removed for topics, or selections of topics. So, when the application no longer needs to update some topics it can clear out those cache entries. Clearing of cache entries will do no harm to subsequent updates on the same topic but will merely mean that it will not be possible to calculate a delta for the next value and therefore the full value will be sent to the server. Any cache entries relating to an update source registration are removed when the registration becomes active and also when it is closed. The cache used by the value updaters is a session-wide cache and thus can be managed and accessed from any updater or from the feature itself.

When using non-exclusive updating, the full value is always sent to the server and values are not cached.

Direct updating

This mechanism is retained for backwards compatibility but TopicUpdateControl.ValueUpdaters are a much better mechanism.

Convenience methods that take Bytes for an update are provided for use for simple updates of any topic type.

Direct updates do not cache values.

Never mix value updating and direct updating for the same topics.

Time series topics

Time series topics have a specific update protocol and are not supported by this feature. Use TimeSeries to update time series topics.

Access control

In order to update any topic a client needs UPDATE_TOPIC permission covering the topic.

In order to register as an update source the client needs REGISTER_HANDLER permission.

Accessing the feature

 
 UpdateControl updateControl = session.feature(TopicUpdateControl.class);
 UpdateCallback callback = new UpdateCallback.Default();

 updateControl.registerUpdateSource("foo/bar", new UpdateSource.Default() {
      private Registration handler;

      public void onRegistered(Registration handler) {
          this.handler = handler;
      }

      public void onActive(String topicPath, Updater updater) {
          // When we're active, send 10 updates to a topic
          final ValueUpdater<String> valueUpdater = updater.valueUpdater(String.class);
          for (int i = 0; i < 10; ++i) {
              valueUpdater.update("foo/bar", "Update: " + i, callback);
          }

          // Finished updating - deregister from server
          handler.close();
      }
 });