Interface TopicUpdate
- All Superinterfaces:
Feature
- All Known Subinterfaces:
Topics
Topics can be set to new values using stateless
set
operations or an UpdateStream
. Both ensure that new values are applied safely to appropriate
topics.
Additionally, JSON topics can be updated with a JSON
Patch
. A patch is a list of operations that modifies a JSON value, removing
the need to supply a complete new value. This is useful if the source of the
updates doesn't provide values. For one-off, small changes to large JSON
values, it can be significantly cheaper to apply a patch than to use
set
to provide the complete value.
Update streams
An update stream is created for a specific topic. An UpdateStreamBuilder can
be obtained using UpdateStream.Builder
. The type of the topic must
match the type of values passed to the update stream. An update stream can be
used to send any number of updates. It sends a sequence of updates for a
specific topic to the server. If supported by the data type, updates will be
sent to the server as a stream of binary deltas.
Update streams have additional ways of failing compared to stateless set operations but when used repeatedly have lower overheads. This is because update streams maintain a small amount of state that reduces the overhead of operations but can become invalid for example, if the topic is deleted, or some other session updates the topic value.
By default, update streams use a form of optimistic locking. An update stream
can update its topic incrementally as long as nothing else updates the topic.
If the topic is updated independently (for example, by another session, or by
the current session via set or a different update stream), then the next
update performed by the update stream will result in an
InvalidUpdateStreamException
.
Applications can chose to use collaborative locking to coordinate exclusive
access to a topic. To follow this pattern acquire a
session lock
, and use it with a
lock constraint
.
The application is responsible for designing a locking scheme which
determines which lock is required to access a particular topic, and for
ensuring that all parts of the application that update the topic follow this
scheme. Lock constraints and an application locking scheme can also ensure a
sequence of set operations has exclusive access to the topic.
Supplying values
When supplying values to an update the value type must be specified
(valueClass parameter). When using update streams, the value type is
specified when creating the stream. The class specified will depend upon the
TopicType
of the topic being updated, according to the supported
types for the corresponding DataType
. For example, for a
JSON
topic, a type of JSON.class
should
be supplied.
Note that for BINARY
topics the value class can be
Binary.class
or Bytes.class
(or any subtype of
these) but the value must be effectively immutable. This means that any array
backing the supplied value must not be changed otherwise immutability would
be violated and results could be unpredictable.
Removing values
When a string
, int64
, or
double
topic is set to null
, the topic will
be updated to have no value. If a previous value was present subscribers will
receive a notification that the new value is null
. New subscribers
will not receive a value notification. Attempting to set any other type of
topic to null
will cause a NullPointerException
to be thrown.
Adding topics
When setting a value using either stateless operations or update streams it
is possible to add a topic if one is not present. This is done using the
addAndSet
methods or providing a topic specification when creating the update stream.
If a topic exists these methods will update the existing topic.
Time series topics
All methods provided by this feature are compatible with time series topics
except for applyJsonPatch(String, String)
. The TimeSeries
feature can be used to update time series topics with custom metadata and
provides query capabilities.
Access control
To update a topic a session needs
UPDATE_TOPIC
permission for the topic path. To create a topic a session
needs
MODIFY_TOPIC
permission for the topic path. Requests that combine adding a
topic and setting the value such as
addAndSet
require both permissions.
Accessing the feature
This feature may be obtained from a session
as follows:
TopicUpdate topicUpdate = session.feature(TopicUpdate.class);
This feature is also extended by the topics feature
. This
means is it possible to use the methods described here through the
topics feature
.
- Since:
- 6.2
- Author:
- DiffusionData Limited
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic final class
Exception thrown to report that applying a JSON Patch failed.static final class
Exception thrown to report that a JSON Patch was invalid.static interface
-
Method Summary
Modifier and TypeMethodDescriptionaddAndSet
(String path, TopicSpecification specification, Class<T> valueClass, T value) Ensures a topic exists and sets its value.addAndSet
(String path, TopicSpecification specification, Class<T> valueClass, T value, UpdateConstraint constraint) Ensures a topic exists and sets its value.applyJsonPatch
(String path, String patch) Applies a JSON Patch to a JSON topic.applyJsonPatch
(String path, String patch, UpdateConstraint constraint) Applies a JSON Patch to a JSON topic.<T> UpdateStream<T>
createUpdateStream
(String path, TopicSpecification specification, Class<T> valueClass) Deprecated.since 6.9<T> UpdateStream<T>
createUpdateStream
(String path, TopicSpecification specification, Class<T> valueClass, UpdateConstraint constraint) Deprecated.since 6.9<T> UpdateStream<T>
createUpdateStream
(String path, Class<T> valueClass) Deprecated.since 6.9<T> UpdateStream<T>
createUpdateStream
(String path, Class<T> valueClass, UpdateConstraint constraint) Deprecated.since 6.9Creates an update stream builder to use for creating update streams.<T> CompletableFuture<?>
Sets the topic to a specified value.<T> CompletableFuture<?>
set
(String path, Class<T> valueClass, T value, UpdateConstraint constraint) Sets the topic to a specified value.Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature
getSession
-
Method Details
-
set
Sets the topic to a specified value.The
null
value can only be passed to thevalue
parameter when updatingstring
,int64
, ordouble
topics.When a
string
,int64
, ordouble
topic is set tonull
, the topic will be updated to have no value. If a previous value was present subscribers will receive a notification that the new value isnull
. New subscribers will not receive a value notification.- Type Parameters:
T
- the type of the value- Parameters:
path
- the path of the topicvalueClass
- the type of the valuevalue
- the value.String
,int64
, anddouble
topics acceptnull
, as described above. Usingnull
with other topic types is an error and will throw aNullPointerException
.- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include:NoSuchTopicException
– if there is no topic bound topath
;IncompatibleTopicException
– if updates cannot be applied to the topic, for example if a topic view has bound a reference topic to the path;IncompatibleTopicStateException
– if the topic is managed by a component (such as fan-out) that prohibits updates from the caller;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
-
set
<T> CompletableFuture<?> set(String path, Class<T> valueClass, T value, UpdateConstraint constraint) Sets the topic to a specified value.Takes a constraint that must be satisfied for the update to be applied.
In other respects this method works in the same way as
set(String, Class, Object)
.- Type Parameters:
T
- the type of the value- Parameters:
path
- the path of the topicvalueClass
- the type of the valuevalue
- the value.String
,int64
, anddouble
topics acceptnull
, as described above. Usingnull
with other topic types is an error and will throw aNullPointerException
.constraint
- the constraint that must be satisfied for the topic to be updated- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include:NoSuchTopicException
– if there is no topic bound topath
;IncompatibleTopicException
– if updates cannot be applied to the topic, for example if a topic view has bound a reference topic to the path;UnsatisfiedConstraintException
– if theconstraint
is not satisfied by the topic bound topath
;IncompatibleTopicStateException
– if the topic is managed by a component (such as fan-out) that prohibits updates from the caller;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
-
addAndSet
<T> CompletableFuture<TopicCreationResult> addAndSet(String path, TopicSpecification specification, Class<T> valueClass, T value) Ensures a topic exists and sets its value.If a topic does not exist at the
path
, one will be created using thespecification
. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail withIncompatibleTopicException
.In other respects this method works in the same way as
set(String, Class, Object)
.- Type Parameters:
T
- the type of the value- Parameters:
path
- the path of the topicspecification
- the required specification of the topicvalueClass
- the type of the valuevalue
- the value.String
,int64
, anddouble
topics acceptnull
, as described above. Usingnull
with other topic types is an error and will throw aNullPointerException
.- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include those reported byset
exceptNoSuchTopicException
as well as:TopicControl.InvalidTopicPathException
–path
is not a valid topic path;TopicControl.InvalidTopicSpecificationException
– the specification is invalid, possibly because mandatory properties not supplied;TopicControl.TopicLicenseLimitException
– the topic could not be added as it would breach a licensing limit;PermissionsException
– if the calling session does not have the appropriate permissions forpath
; in general the calling session must have theMODIFY_TOPIC
andUPDATE_TOPIC
permissions, but if the topic exists and has the same specification then it's sufficient for the calling session's principal to be thetopic owner
.
- Throws:
IllegalArgumentException
- if the type of the specification does not match the type of the update
-
addAndSet
<T> CompletableFuture<TopicCreationResult> addAndSet(String path, TopicSpecification specification, Class<T> valueClass, T value, UpdateConstraint constraint) Ensures a topic exists and sets its value.If a topic does not exist at the
path
, one will be created using thespecification
. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail withIncompatibleTopicException
.Takes a constraint that must be satisfied for the topic to be created or the update to be applied.
In other respects this method works in the same way as
set(String, Class, Object)
.- Type Parameters:
T
- the type of the value- Parameters:
path
- the path of the topicspecification
- the required specification of the topicvalueClass
- the type of the valuevalue
- the value.String
,int64
, anddouble
topics acceptnull
, as described above. Usingnull
with other topic types is an error and will throw aNullPointerException
.constraint
- the constraint that must be satisfied for the topic to be updated- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include those reported byset
exceptNoSuchTopicException
as well as:TopicControl.InvalidTopicPathException
–path
is not a valid topic path;TopicControl.InvalidTopicSpecificationException
– the specification is invalid, possibly because mandatory properties not supplied;TopicControl.TopicLicenseLimitException
– the topic could not be added as it would breach a licensing limit;PermissionsException
– if the calling session does not have theMODIFY_TOPIC
and theUPDATE_TOPIC
permissions forpath
;
- Throws:
IllegalArgumentException
- if the type of the specification does not match the type of the update
-
createUpdateStream
Deprecated.since 6.9Creates anupdate stream
to use for updating a specific topic.The type of the topic being updated must match the type derived from the
valueClass
parameter.Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with
session locks
as constraints.Streams are validated lazily when the first
UpdateStream.set(T)
orUpdateStream.validate()
operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.- Type Parameters:
T
- type of the values expected by the update stream- Parameters:
path
- the path of the topicvalueClass
- the type of the values expected by the update stream- Returns:
- an update stream
-
createUpdateStream
@Deprecated <T> UpdateStream<T> createUpdateStream(String path, Class<T> valueClass, UpdateConstraint constraint) Deprecated.since 6.9Creates anupdate stream
to use for updating a specific topic.Takes a constraint that must be satisfied for the update stream to be validated.
In other respects this method works in the same way as
createUpdateStream(String, Class)
.- Type Parameters:
T
- type of the values expected by the update stream- Parameters:
path
- the path of the topicvalueClass
- the type of the values expected by the update streamconstraint
- the constraint that must be satisfied for the update stream to be validated- Returns:
- an update stream
-
createUpdateStream
@Deprecated <T> UpdateStream<T> createUpdateStream(String path, TopicSpecification specification, Class<T> valueClass) Deprecated.since 6.9Creates anupdate stream
to use for creating and updating a specific topic.If a topic does not exist at the
path
one will be created using thespecification
when the update stream is validated. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail withIncompatibleTopicException
.In other respects this method works in the same way as
createUpdateStream(String, Class)
.- Type Parameters:
T
- type of the values expected by the update stream- Parameters:
path
- the path of the topicspecification
- the required specification of the topicvalueClass
- the type of the values expected by the update stream- Returns:
- an update stream
- Throws:
IllegalArgumentException
- if the topic type of the specification does not match the type of values
-
createUpdateStream
@Deprecated <T> UpdateStream<T> createUpdateStream(String path, TopicSpecification specification, Class<T> valueClass, UpdateConstraint constraint) Deprecated.since 6.9Creates anupdate stream
to use for creating and updating a specific topic.If a topic does not exist at the
path
one will be created using thespecification
when the update stream is validated. If a topic does exist, its specification must matchspecification
, otherwise the operation will fail withIncompatibleTopicException
.Takes a constraint that must be satisfied for the update stream to be validated.
In other respects this method works in the same way as
createUpdateStream(String, Class)
.- Type Parameters:
T
- type of the values expected by the update stream- Parameters:
path
- the path of the topicspecification
- the required specification of the topicvalueClass
- the type of the values expected by the update streamconstraint
- the constraint that must be satisfied for the update stream to be validated- Returns:
- an update stream
- Throws:
IllegalArgumentException
- if the topic type of the specification does not match the type of values
-
newUpdateStreamBuilder
UpdateStream.Builder newUpdateStreamBuilder()Creates an update stream builder to use for creating update streams.- Returns:
- an update stream builder
- Since:
- 6.9
-
applyJsonPatch
Applies a JSON Patch to a JSON topic.The
patch
argument should be formatted according to the JSON Patch standard (RFC 6902).Patches are a sequence of JSON Patch operations contained in an array. They are applied as an atomic update to the previous value if the resulting update is successfully calculated. The following patch will check the value at a specific key and update if the expected value is correct:
[{"op":"test", "path":"/price", "value" : 22}, {"op":"add", "path":"/price", "value": 23}]
The available operations are:
- Add:
{"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}
- Remove:
{"op": "remove", "path": "/a/b/c"}
- Replace:
{"op": "replace", "path": "/a/b/c", "value": 43}
- Move:
{"op": "move", "from": "/a/b/c", "path": "/a/b/d"}
- Copy:
{"op": "copy", "from": "/a/b/c", "path": "/a/b/e"}
- Test:
{"op": "test", "path": "/a/b/c", "value": "foo"}
The test operation checks that the CBOR representation of the value of a topic is identical to the value provided in the patch after converting it to CBOR. If the value is represented differently as CBOR, commonly due to different key ordering, then the patch will return the index of the failed operation . e.g the values
{"foo": "bar", "count": 43}
and{"count": 43, "foo": "bar"}
are unequal despite semantic equality due to the differences in a byte for byte comparison.- Parameters:
path
- the path of the topic to patchpatch
- the JSON Patch- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include:TopicUpdate.InvalidPatchException
– if the patch is not a valid JSON Patch;TopicUpdate.FailedPatchException
– if applying the patch fails, this will occur if the topic's present value is invalid CBOR (seeTopicSpecification.VALIDATE_VALUES
);NoSuchTopicException
– if there is no topic bound topath
;IncompatibleTopicException
– if patch cannot be applied to the topic, for example if the topic type is notJSON
.IncompatibleTopicStateException
– if the topic is managed by a component (such as fan-out) that prohibits updates from the caller;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
- Since:
- 6.4
- See Also:
- Add:
-
applyJsonPatch
CompletableFuture<TopicUpdate.JsonPatchResult> applyJsonPatch(String path, String patch, UpdateConstraint constraint) Applies a JSON Patch to a JSON topic.Takes a constraint that must be satisfied for the update to be applied.
In other respects this method works in the same way as
applyJsonPatch(String, String)
.- Parameters:
path
- the path of the topic to patchpatch
- the JSON Patchconstraint
- the constraint that must be satisfied for the patch to be applied- Returns:
- a CompletableFuture that completes when a response is received
from the server.
If the task fails, the CompletableFuture will complete exceptionally with a
CompletionException
. Common reasons for failure, listed by the exception reported as thecause
, include:TopicUpdate.InvalidPatchException
– if the patch is not a valid JSON patch;TopicUpdate.FailedPatchException
– if applying the patch fails, this will occur if the topic's present value is invalid CBOR (seeTopicSpecification.VALIDATE_VALUES
);NoSuchTopicException
– if there is no topic bound topath
;IncompatibleTopicException
– if patch cannot be applied to the topic, for example if the topic type is notJSON
.IncompatibleTopicStateException
– if the topic is managed by a component (such as fan-out) that prohibits updates from the caller;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
- Since:
- 6.4
- See Also:
-