 |
Diffusion .NET Client Library
6.1.5
|
|
Diffusion .NET Client Library
6.1.5
|
Represents a feature that provides a client session with the ability to update topics at the server. More...
Public Member Functions | |
| void | RegisterUpdateSource (string topicPath, ITopicUpdateSource updateSource) |
| Registers an ITopicUpdateSource for a branch of the topic tree. More... | |
| TFactory | UpdateFactory< TFactory > () |
| Returns an instance of the update factory to create IUpdates of a type corresponding to the given factory type. More... | |
| object | GetCachedValue (string topicPath) |
| Returns the current cached value for a given topic path. More... | |
| void | RemoveCachedValues (string topics) |
| Removes values from the cache. More... | |
| void | RemoveCachedValues (ITopicSelector topics) |
| Removes values from the cache. More... | |
| void | ClearCachedValues () |
| Clears the update value cache. More... | |
Properties | |
| ITopicUpdater | Updater [get] |
| Returns an updater to use for non-exclusive updating. More... | |
 Properties inherited from PushTechnology.ClientInterface.Client.Features.IFeature | |
| ISession | Session [get] |
| Returns the session that the feature is associated with. More... | |
Represents a feature that provides a client session with the ability to update topics at the server.
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 topic type 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 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 deregistered, the server will promote one of the other sources to an active state.
If registration succeeds, OnRegistered will be called with a IRegistration 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 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 (e.g. JSON) is using a IValueUpdater{TValue}.
A value updater is obtained from the Updater using the ITopicUpdater.ValueUpdater{TValue} property. The class specified will indicate which topic types may be updated using the updater (so for TopicType.JSON specify IJSON).
The topic is updated by simply using the IValueUpdater{TValue}.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 ITopicUpdateSource.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 via the ITopicUpdater is the only mechanism available for updating topics that are not based on data types. 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.
Convenience methods that take IBytes or strings for an update are provided for use for simple updates, whereas the methods that take an IUpdate object cater for more complex requirements. Such updates may be created using a suitable factory obtained using UpdateFactory{TF}.
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 session as follows:
Since 5.0
| void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.ClearCachedValues | ( | ) |
Clears the update value cache.
Value updaters cache the last value sent to the server so that subsequent updates can calculate deltas to send for efficiency. This allows the cache to be cleared.
If a cached value is removed, the next update for a topic will transmit the whole value to the server rather than a delta.
Since 5.8
| object PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.GetCachedValue | ( | string | topicPath | ) |
Returns the current cached value for a given topic path.
Cached values are only maintained for topics that are updated using value updaters. When an updater sends an update the latest value is cached so that more efficient delta updates can be performed subsequently.
Since 5.8
| topicPath | The topic path to obtain the current value for. |
| void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.RegisterUpdateSource | ( | string | topicPath, |
| ITopicUpdateSource | updateSource | ||
| ) |
Registers an ITopicUpdateSource for a branch of the topic tree.
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 which will provide a IRegistration. This may be used to deregister the update source from the associated branch at a later point in time.
When an update source is registered, it will have either OnActive or OnStandby called, depending on the initial state that the server assigns. Subsequent state changes will result in further calls to these methods.
OnActive 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 will be called when this source may no longer provide updates on the specified branch. Any updater instances previously provided to this source via the OnActive callback are now invalid; using such an instance will result in an immediate call to the OnError method of the callback.
When this source is deliberately closed via Close or as a result of server-side actions, or if the session is closed OnClose will be called.
Unexpected failures, such as registration failing, will result in a call to OnError instead.
Since 5.1
| topicPath | The topic path to register the update source on. |
| updateSource | The update source to register. |
| void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.RemoveCachedValues | ( | string | topics | ) |
Removes values from the cache.
Cached values are only maintained for topics that are updated using value updaters. When an updater sends an update the latest value is cached so that more efficient delta updates can be performed subsequently.
If a cached value is removed, the next update for a topic will transmit the whole value to the server rather than a delta.
Since 5.8
| topics | The selector expression - all values for topics that match the expression will be removed. |
| void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.RemoveCachedValues | ( | ITopicSelector | topics | ) |
Removes values from the cache.
Cached values are only maintained for topics that are updated using value updaters. When an updater sends an update the latest value is cached so that more efficient delta updates can be performed subsequently.
If a cached value is removed, the next update for a topic will transmit the whole value to the server rather than a delta.
Since 5.8
| topics | The selector - all values for topics that match the selector will be removed. |
| TFactory PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicUpdateControl.UpdateFactory< TFactory > | ( | ) |
Returns an instance of the update factory to create IUpdates of a type corresponding to the given factory type.
Since 5.1
| TFactory | The factory type. |
| TFactory | : | IUpdateFactory |
|
get |
Returns an updater to use for non-exclusive updating.
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 ITopicUpdater.ValueUpdater{TValue} is used to obtain updater specific to the topic type.
Since 5.3
1.8.5 
