Interface IUpdateStream<TValue>
The update stream for updating a specific topic.
Namespace: PushTechnology.ClientInterface.Client.Features
Assembly: Diffusion.Client.dll
Syntax
public interface IUpdateStream<TValue>
Type Parameters
Name | Description |
---|---|
TValue | The value type. |
Remarks
An update stream is associated with a specific topic. The type of the topic must match the type of values passed to the update stream. It can be created with an optional IUpdateConstraint. The existence of the topic, its type and the constraint are validated lazily by the first SetAsync(TValue) or ValidateAsync() 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. An update stream does not prevent other sessions from updating the topic. If exclusive access is required update streams should be used with ISessionLock 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.
Properties
Value
Gets the latest value of the topic set using this update stream.
Declaration
TValue Value { get; }
Property Value
Type | Description |
---|---|
TValue | The cached value of the topic. |
Remarks
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.
Methods
SetAsync(TValue)
Sets the topic to a specified value.
Declaration
Task<TopicCreationResult> SetAsync(TValue value)
Parameters
Type | Name | Description |
---|---|---|
TValue | value | The value. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists. The topic is only added if the
stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification),
and only during the first call of this method. Any subsequent calls will not attempt to add the topic.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics 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 can fail with NoSuchTopicException (if the stream was created without ITopicSpecification) or IncompatibleTopicException. Subsequent calls can fail with InvalidUpdateStreamException. Any call can fail with ClusterRoutingException, SessionSecurityException, or SessionClosedException.
If a IUpdateConstraint was provided when creating the update stream, the first call to this method can also fail with UnsatisfiedConstraintException.
If the update stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification), the first call to this method can also fail with IncompatibleExistingTopicException and it will not fail with NoSuchTopicException.
If this method fails all subsequent calls to SetAsync(TValue) or ValidateAsync() will fail with InvalidUpdateStreamException.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to the update stream's path. Thrown by the returned |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
InvalidUpdateStreamException | The update stream has been invalidated. Thrown by the returned |
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRoutingException | A transient cluster error occurred. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC or
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
See Also
SetAsync(TValue, CancellationToken)
Sets the topic to a specified value.
Declaration
Task<TopicCreationResult> SetAsync(TValue value, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
TValue | value | The value. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists. The topic is only added if the
stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification),
and only during the first call of this method. Any subsequent calls will not attempt to add the topic.
The null
value can only be passed to the value
parameter when updating
STRING, INT64, or
DOUBLE topics.
When any of the previously mentioned topics 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 can fail with NoSuchTopicException (if the stream was created without ITopicSpecification) or IncompatibleTopicException. Subsequent calls can fail with InvalidUpdateStreamException. Any call can fail with ClusterRoutingException, SessionSecurityException, or SessionClosedException.
If a IUpdateConstraint was provided when creating the update stream, the first call to this method can also fail with UnsatisfiedConstraintException.
If the update stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification), the first call to this method can also fail with IncompatibleExistingTopicException and it will not fail with NoSuchTopicException.
If this method fails all subsequent calls to SetAsync(TValue) or ValidateAsync() will fail with InvalidUpdateStreamException.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to the update stream's path. Thrown by the returned |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
InvalidUpdateStreamException | The update stream has been invalidated. Thrown by the returned |
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRoutingException | A transient cluster error occurred. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC or
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
ValidateAsync()
Validates the update stream.
Declaration
Task<TopicCreationResult> ValidateAsync()
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists. The topic is only added if the
stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification),
and only during the first call of this method. Any subsequent calls will not attempt to add the topic.
Update streams are validated lazily when setting the value via SetAsync(TValue). 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 IncompatibleExistingTopicException if it is the first call to ValidateAsync(), SetAsync(TValue) has not been called and a ITopicSpecification was provided when creating the update stream, otherwise it will never fail with this cause.
The first call to this method can fail with NoSuchTopicException (if the stream was created without ITopicSpecification) or IncompatibleTopicException. Subsequent calls can fail with InvalidUpdateStreamException. Any call can fail with ClusterRoutingException, SessionSecurityException, or SessionClosedException.
If a IUpdateConstraint 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 CreateUpdateStream<TValue>(String, ITopicSpecification), the first call to this method may also fail with IncompatibleExistingTopicException and it will not fail with NoSuchTopicException.
If this method fails all subsequent calls to SetAsync(TValue) or ValidateAsync() will fail with InvalidUpdateStreamException.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to the update stream's path. Thrown by the returned |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
InvalidUpdateStreamException | The update stream has been invalidated. Thrown by the returned |
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRoutingException | A transient cluster error occurred. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC or
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |
ValidateAsync(CancellationToken)
Validates the update stream.
Declaration
Task<TopicCreationResult> ValidateAsync(CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<TopicCreationResult> | The |
Remarks
If the task completes successfully, the Task
result will be
CREATED if the topic has been created, or
EXISTS if the topic already exists. The topic is only added if the
stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification),
and only during the first call of this method. Any subsequent calls will not attempt to add the topic.
Update streams are validated lazily when setting the value via SetAsync(TValue). 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 can fail with IncompatibleExistingTopicException if it is the first call to ValidateAsync(), SetAsync(TValue) has not been called and a ITopicSpecification was provided when creating the update stream, otherwise it will never fail with this cause.
The first call to this method can fail with NoSuchTopicException (if the stream was created without ITopicSpecification) or IncompatibleTopicException. Subsequent calls can fail with InvalidUpdateStreamException. Any call can fail with ClusterRoutingException, SessionSecurityException, or SessionClosedException.
If a IUpdateConstraint was provided when creating the update stream, the first call to this method can also fail with UnsatisfiedConstraintException.
If the update stream was created with CreateUpdateStream<TValue>(String, ITopicSpecification), the first call to this method can also fail with IncompatibleExistingTopicException and it will not fail with NoSuchTopicException.
If this method fails all subsequent calls to SetAsync(TValue) or ValidateAsync() will fail with InvalidUpdateStreamException.
Exceptions
Type | Condition |
---|---|
NoSuchTopicException | There is no topic bound to the update stream's path. Thrown by the returned |
IncompatibleTopicException | Updates cannot be applied to the topic because the topic does not support updates. Thrown by the returned
|
IncompatibleTopicStateException | The topic is managed by a component (such as fan-out) that prohibits updates from the caller. Thrown by the
returned |
UnsatisfiedConstraintException | The |
InvalidUpdateStreamException | The update stream has been invalidated. Thrown by the returned |
InvalidTopicPathException |
|
InvalidTopicSpecificationException | The specification is invalid, possibly because mandatory properties were not supplied. Thrown by the returned
|
TopicLicenseLimitException | The topic could not be added as it would breach a licensing limit. Thrown by the returned
|
ClusterRoutingException | A transient cluster error occurred. Thrown by the returned |
SessionSecurityException | The calling session does not have MODIFY_TOPIC or
UPDATE_TOPIC permission for |
SessionClosedException | The session is closed. Thrown by the returned |