T
- type of the valuepublic interface UpdateStream<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:
UPDATE_TOPIC
permission
Update streams are thread-safe.
Modifier and Type | Interface and Description |
---|---|
static interface |
UpdateStream.Builder
Builder for
update stream to use for updating a
specific topic. |
Modifier and Type | Method and Description |
---|---|
T |
get()
Return the latest value of the topic set using this update stream.
|
CompletableFuture<TopicCreationResult> |
set(T value)
Sets the topic to a specified value.
|
CompletableFuture<TopicCreationResult> |
validate()
Validates the update stream.
|
CompletableFuture<TopicCreationResult> set(T value)
The null
value can only be passed to the value
parameter when updating string
,
int64
, or double
topics.
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.
The first call to this method may fail with
NoSuchTopicException
or IncompatibleTopicException
.
Subsequent calls may fail with InvalidUpdateStreamException
.
Any call can fail with ClusterRoutingException
,
PermissionsException
or SessionClosedException
.
If a constraint
was provided when creating the
update stream, the first call to this method may also fail with
UnsatisfiedConstraintException
.
If the update stream was created with a TopicSpecification
,
the first call to this method may also fail with
TopicControl.IncompatibleExistingTopicException
and it will not fail with
NoSuchTopicException
.
If this method fails all subsequent calls to set(T)
or
validate()
will fail with InvalidUpdateStreamException
.
value
- the value. Update streams for
string
,
int64
, and
double
topics accept null
, as described above. Using
null with other topic types is an error and will result
in a NullPointerException
.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
NoSuchTopicException
– if there is no topic
bound to path
;
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 the
constraint
is not satisfied by the topic path
;
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 the MODIFY_TOPIC
or
UPDATE_TOPIC
permission for path
;
SessionClosedException
– if the session is
closed.
T get()
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.
IllegalStateException
- if called before the first call to
set(T)
CompletableFuture<TopicCreationResult> validate()
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 to validate()
, set(T)
has not
been called and a topic 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
or IncompatibleTopicException
.
Subsequent calls may fail with InvalidUpdateStreamException
.
Any call can fail with ClusterRoutingException
,
PermissionsException
or SessionClosedException
.
If a constraint
was provided when creating the
update stream, the first call to this method may also fail with
UnsatisfiedConstraintException
.
If the update stream was created with a TopicSpecification
,
the first call to this method may also fail with
TopicControl.IncompatibleExistingTopicException
and it will not fail with
NoSuchTopicException
.
If this method fails all subsequent calls to set(T)
or
validate()
will fail with InvalidUpdateStreamException
.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
NoSuchTopicException
– if there is no topic
bound to path
;
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 the
constraint
is not satisfied by the topic path
;
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 the MODIFY_TOPIC
or
UPDATE_TOPIC
permission for path
;
SessionClosedException
– if the session is
closed.
Copyright © 2024 DiffusionData Ltd. All Rights Reserved.