Interface ITopicUpdateControl
Represents a feature that provides a client session with the ability to update topics at the server.
Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features.Control.Topics
Assembly: Diffusion.Client.dll
Syntax
public interface ITopicUpdateControl : IFeature
Remarks
Deprecated: This feature has been replaced by the ITopicUpdate feature and will be removed in a future release. The ITopicUpdate feature provides equivalent and additional functionality, such as conditional updates.
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 ITopicUpdater is needed to send the updates. The way in which the updater is obtained is dependent upon the mode (see below).
Any TopicType may be updated using the updater directly (see "Direct updating" below) but the preferred mechanism for IDataType<TValue> based topics 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.
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 ITopicUpdateSource for a branch of the topic tree using RegisterUpdateSource(String, ITopicUpdateSource).
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 deregistered, the server will promote one of the other sources to an active state.
If registration succeeds, OnRegistered(String, IRegistration) will be called with a IRegistration instance. The CloseAsync() method of the registration can later be called to CloseAsync() the source.
When the source becomes active it will be notified through the OnActive(String, ITopicUpdater) method which provides an ITopicUpdater which can be used to send updates.
Non-exclusive updating
The client can perform non-exclusive updates using an updater obtained from the Updater property. 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 updating IDataType<TValue> based topics (for example JSON) is using a IValueUpdater<TValue>.
A value updater is obtained from the Updater using the ValueUpdater<TValue>() property. The class specified will indicate which topic types may be updated using the updater (so for JSON specify IJSON).
The topic is updated by simply using the Update(String, TValue, ITopicUpdaterUpdateCallback) method to specify a new value. 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 OnActive(String, ITopicUpdater) active and also when it is closed.
When using non-exclusive updating, the full value is always sent to the server, and the values are not cached.
Direct updating
Direct updating of topics through the ITopicUpdater is the only mechanism available for updating topics that are not based on IDataType<TValue>. These topic types will, in future releases, be replaced by new IDataType<TValue> based topics. This mechanism can be used for any topic type but is not recommended for those based on IDataTypes as IValueUpdater<TValue>s are a much better mechanism.
Direct updates do not cache values.
Never mix value updating and direct updating for the same 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
This feature may be obtained from a ISession as follows:
var topicUpdates = session.TopicUpdateControl;
Since 5.0
Properties
Updater
Returns an updater to use for non-exclusive updating.
Declaration
ITopicUpdater Updater { get; }
Property Value
Type | Description |
---|---|
ITopicUpdater |
Remarks
The updater may be used to send updates to any topic that the client has permission to update. However, an update will fail if there is already a registered exclusive update source for the topic.
For topics that are supported by IDataType<TValue>s it is recommended that ValueUpdater<TValue>() is used to obtain updater specific to the topic type.
Since 5.3
Methods
RegisterUpdateSource(String, ITopicUpdateSource)
Registers an ITopicUpdateSource for a branch of the topic tree.
Declaration
void RegisterUpdateSource(string topicPath, ITopicUpdateSource updateSource)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to register the update source on. |
ITopicUpdateSource | updateSource | The update source to register. |
Remarks
This registers the current client session as an update source for a specified branch of the topic tree, thus allowing updating of topics in that branch.
If the registration is successful there will be a callback on OnRegistered(String, IRegistration) which will provide a IRegistration. This may be used to CloseAsync() the update source from the associated branch at a later point in time.
When an update source is registered, it will have either OnActive(String, ITopicUpdater) or OnStandby(String) called, depending on the initial state that the server assigns. Subsequent state changes will result in further calls to these methods.
OnActive(String, ITopicUpdater) will be called when the server determines it is valid to send topic updates on the specified branch. This callback will be provided with an ITopicUpdater, which allows updates to be performed.
OnStandby(String) will be called when this source may no longer provide updates on the specified branch. Any updater instances previously provided to this source through the OnActive callback are now invalid; using such an instance will result in an immediate call to the OnError(String, ErrorReason) method of the callback.
When this source is deliberately closed through CloseAsync() or as a result of server-side actions, or if the session is closed OnClose(String) will be called.
Unexpected failures, such as registration failing, will result in a call to OnError(String, ErrorReason) instead.
Since 5.1