Interface UpdateStream<T>
- Type Parameters:
T
- type of the value
- All Known Subinterfaces:
RecoverableUpdateStream<T>
An update stream is associated with a specific topic.
Update streams are created using TopicUpdate.newUpdateStreamBuilder()
.
It can be created with an optional constraint
. An
optional TopicSpecification
can be provided on creation.
The type of the topic must match the type of values passed to the update stream.
The existence of the topic, its type and the constraint are validated lazily
by the first set(T)
or validate()
operation. Subsequent operations issued before the first operation
completes will be deferred until the completion of the first operation.
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 by
default. Optionally, deltas can be disabled when creating the stream.
An update stream does not prevent other sessions from updating the topic. If
exclusive access is required update streams should be used with
session locks
as constraints.
Once validated an update stream can be invalidated. An invalidated update stream rejects the operations applied to it. The update stream will be invalidated if:
- the topic is removed
- another update stream is created for the same topic
- the topic is updated to a new value by anything other than the stream
- the session does not have the
UPDATE_TOPIC
permission - an operation fails because of cluster repartitioning
Update streams are thread-safe.
- Since:
- 6.2
- Author:
- DiffusionData Limited
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Builder forupdate stream
to use for updating a specific topic. -
Method Summary
-
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.The first call to this method may fail with
NoSuchTopicException
orIncompatibleTopicException
. Subsequent calls may fail withInvalidUpdateStreamException
. Any call can fail withClusterRoutingException
,PermissionsException
orSessionClosedException
.If a
constraint
was provided when creating the update stream, the first call to this method may also fail withUnsatisfiedConstraintException
.If the update stream was created with a
TopicSpecification
, the first call to this method may also fail withTopicControl.IncompatibleExistingTopicException
and it will not fail withNoSuchTopicException
.If this method fails all subsequent calls to
set(T)
orvalidate()
will fail withInvalidUpdateStreamException
.- Parameters:
value
- the value. Update streams forstring
,int64
, anddouble
topics acceptnull
, as described above. Using null with other topic types is an error and will result in 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;UnsatisfiedConstraintException
– if theconstraint
is not satisfied by the topicpath
;InvalidUpdateStreamException
– the update stream has been invalidated;TopicControl.InvalidTopicPathException
–topicPath
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;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;PermissionsException
– if a specification has been provided to the stream and the calling session does not have theMODIFY_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
-
get
T get()Return the latest value of the topic set using this update stream.The returned value reflects the last value that has been set, before it is sent to the server.
If the server rejects a set operation, the topic value will not change and this update stream will be invalidated.
- Returns:
- the cached value of the topic
- Throws:
IllegalStateException
- if called before the first call toset(T)
-
validate
CompletableFuture<TopicCreationResult> validate()Validates the update stream.Update streams are validated lazily when
setting the value
. This method allows the stream to be validated before a value needs to be set.If the update stream has not been validated yet, calling this method checks the topic exists, the topic type is correct, the constraint is satisfied and the session has permission to update the topic. Once it has been validated calling this method checks the topic has not been removed, no other stream has been created for the topic, the value of the topic has not been changed by anything else and the session still has permission to update the topic.
This method may fail with
TopicControl.IncompatibleExistingTopicException
if it is the first call tovalidate()
,set(T)
has not been called and atopic specification
was provided when creating the update stream, otherwise it will never fail with this cause.The first call to this method may fail with
NoSuchTopicException
orIncompatibleTopicException
. Subsequent calls may fail withInvalidUpdateStreamException
. Any call can fail withClusterRoutingException
,PermissionsException
orSessionClosedException
.If a
constraint
was provided when creating the update stream, the first call to this method may also fail withUnsatisfiedConstraintException
.If the update stream was created with a
TopicSpecification
, the first call to this method may also fail withTopicControl.IncompatibleExistingTopicException
and it will not fail withNoSuchTopicException
.If this method fails all subsequent calls to
set(T)
orvalidate()
will fail withInvalidUpdateStreamException
.- 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;UnsatisfiedConstraintException
– if theconstraint
is not satisfied by the topicpath
;InvalidUpdateStreamException
– the update stream has been invalidated;ClusterRoutingException
– if the operation failed due to a transient cluster error;PermissionsException
– if the calling session does not have theUPDATE_TOPIC
permission forpath
;PermissionsException
– if a specification has been provided to the stream and the calling session does not have theMODIFY_TOPIC
permission forpath
;SessionClosedException
– if the session is closed.
-