public interface TopicUpdateControl extends Feature
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 for DataType
based topics is to use "Live 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. Live 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.
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.
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.
DataType
based topics (e.g. 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.
TopicUpdateControl.Updater
is
the only mechanism available for updating topics that are not based on
DataType
s. These topic types will, in future releases, be replaced by
new DataType
based topics. This mechanism can be used for any topic
type but is not recommended for those based on DataTypes
as
TopicUpdateControl.ValueUpdater
s are a much better mechanism.
Convenience methods that take Bytes
or strings
for an update are provided for use for simple updates, whereas the methods
that take an Update
object cater for more complex requirements. Such
updates may be created using a suitable factory obtained using
updateFactory(Class)
.
Direct updates do not cache values.
Never mix value updating and direct updating for the same topics.
UPDATE_TOPIC
permission covering the
topic.
In order to register as an update source the client needs
REGISTER_HANDLER
permission.
session
as follows:
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
for (int i = 0; i < 10; ++i) {
final Content content =
Diffusion.content().newContent("Update: " + i);
updater.update("foo/bar", content, callback);
}
// Finished updating - deregister from server
handler.close();
}
});
Modifier and Type | Interface and Description |
---|---|
static interface |
TopicUpdateControl.Updater
An Updater provides methods for updating topics.
|
static interface |
TopicUpdateControl.UpdateSource
A source of updates which may be registered in order to update parts of
the topic tree.
|
static interface |
TopicUpdateControl.ValueUpdater<V>
An updater that may be used to update topics of a certain type by
specifying new values.
|
Modifier and Type | Field and Description |
---|---|
static ErrorReason |
DELTA_WITHOUT_VALUE
An attempt has been made to apply a delta to a topic that has not yet has
a value specified for it.
|
static ErrorReason |
DUPLICATES
For topic types that operate a policy to prevent duplicate data an update
has been supplied that violates the duplicates policy.
|
static ErrorReason |
EXCLUSIVE_UPDATER_CONFLICT
A non-exclusive update has been attempted when an exclusive update source
is already registered for the specified topic's branch.
|
static ErrorReason |
INCOMPATIBLE_UPDATE
An update has been supplied which is incompatible with the type of topic
that it is being applied to.
|
static ErrorReason |
INVALID_ADDRESS
For topic types with addressable data a supplied key or index is invalid
or does not correspond to a current entry.
|
static ErrorReason |
INVALID_UPDATER
The updater used is not in a valid state for sending updates.
|
static ErrorReason |
MISSING_TOPIC
A topic with the path specified for the update does not exist.
|
static ErrorReason |
UPDATE_FAILED
The update failed, probably because the content sent with the update was
invalid or incompatible with the topic type or expected data format.
|
Modifier and Type | Method and Description |
---|---|
void |
clearCachedValues()
Clears the update value cache.
|
Object |
getCachedValue(String topicPath)
Returns the current cached value for a given topic path.
|
void |
registerUpdateSource(String topicPath,
TopicUpdateControl.UpdateSource updateSource)
Register an
TopicUpdateControl.UpdateSource for a branch of the topic tree. |
void |
removeCachedValues(String topics)
Removes values from the cache.
|
void |
removeCachedValues(TopicSelector topics)
Removes values from the cache.
|
<F extends UpdateFactory> |
updateFactory(Class<F> factoryType)
Returns an instance of the update factory to create
Update s of a
type corresponding to a given factory type. |
TopicUpdateControl.Updater |
updater()
Return an updater to use for non-exclusive updating.
|
getSession
static final ErrorReason INCOMPATIBLE_UPDATE
ContentUpdateFactory
has been supplied for a
Paged Record
topic or an update has been
attempted for a topic type that cannot be updated (e.g. functional
topics).static final ErrorReason UPDATE_FAILED
static final ErrorReason INVALID_UPDATER
static final ErrorReason MISSING_TOPIC
static final ErrorReason EXCLUSIVE_UPDATER_CONFLICT
static final ErrorReason DELTA_WITHOUT_VALUE
static final ErrorReason INVALID_ADDRESS
static final ErrorReason DUPLICATES
TopicUpdateControl.Updater updater() throws SessionClosedException
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 DataType
s it is recommended that
TopicUpdateControl.Updater.valueUpdater(java.lang.Class<V>)
is used to obtain updater specific to the
topic type.
SessionClosedException
- if the session is closedvoid registerUpdateSource(String topicPath, TopicUpdateControl.UpdateSource updateSource) throws IllegalArgumentException, SessionClosedException
TopicUpdateControl.UpdateSource
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 Registration
. 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 updater
, 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.
topicPath
- the topic pathupdateSource
- the update sourceIllegalArgumentException
- if the topic path or source is invalidSessionClosedException
- if the session is closed<F extends UpdateFactory> F updateFactory(Class<F> factoryType) throws IllegalArgumentException, UnsupportedOperationException
Update
s of a
type corresponding to a given factory type.F
- update factory typefactoryType
- the factory typefactoryType
IllegalArgumentException
- if factoryType
is nullUnsupportedOperationException
- if there is no available factory
for the type specified in factoryType
Object getCachedValue(String topicPath) throws IllegalArgumentException
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.
topicPath
- specifies the topic to obtain the current value forTopicType
).IllegalArgumentException
- if topicPath
is nullvoid removeCachedValues(String topics) throws IllegalArgumentException
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.
topics
- selector expression - all values for topics that match the
expression will be removedIllegalArgumentException
- if topicSelector
is null or
invalidvoid removeCachedValues(TopicSelector topics) throws IllegalArgumentException
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.
topics
- all values for topics that match the selector will be
removedIllegalArgumentException
- if topicSelector
is null or
invalidvoid clearCachedValues()
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.
Copyright © 2016 Push Technology Ltd. All Rights Reserved.