Diffusion Apple API  6.3.3
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
Class Methods | Instance Methods | List of all members
PTDiffusionUpdateStream Class Reference

Introduction

An update stream that provides a base functionality for updating a specific topic.

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 PTDiffusionUpdateConstraint. The existence of the topic, its type and the constraint are validated lazily by the first 'set' 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. An update stream does not prevent other sessions from updating the topic. If exclusive access is required update streams should be used with a PTDiffusionSessionLock as a constraint.

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 streams are thread-safe.

See Also
PTDiffusionTopicUpdateFeature
Since
6.3
Inheritance diagram for PTDiffusionUpdateStream:
PTDiffusionBinaryUpdateStream PTDiffusionJSONUpdateStream PTDiffusionNumberUpdateStream PTDiffusionRecordV2UpdateStream PTDiffusionStringUpdateStream

Class Methods

(instancetype) + NS_UNAVAILABLE
 

Instance Methods

(instancetype) - NS_UNAVAILABLE
 
(BOOL) - validateWithCompletionHandler:error:
 

Method Documentation

- (BOOL) validateWithCompletionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

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 an "incompatible existing topic" error if it is the first call to validate, set has not been called and a PTDiffusionTopicSpecification was provided when creating the update stream, otherwise it will never fail with this error.

The first call to this method may fail with a "no such topic" or "incompatible topic" error. Subsequent calls may fail with "invalid update stream". Any call can fail with a "cluster repartition", "session security" or "session closed" error.

If a PTDiffusionUpdateConstraint was provided when creating the update stream, the first call to this method may also fail with an "unsatisified constraint" error.

If the update stream was created with one of the "create update stream" methods, the first call to this method may also fail with an "incompatible existing topic" error and it will not fail with a "no such topic" error.

If this method fails all subsequent calls to 'set' or 'validate' will fail with an "invalid update stream" error.

If the task fails, the completionHandler will be called with an error. Common reasons for failure include:

  • no such topic if there is no topic bound to path.
  • incompatible topic if updates cannot be applied to the topic, for example if the topic is a PTDiffusionTopicType_Slave.
  • incompatible topic state if the topic is managed by a component (such as fan-out) that prohibits updates from the caller.
  • exclusive updater conflict if updates cannot be applied to the topic because an exclusive PTDiffusionTopicUpdateSource is registered for its path.
  • unsatisfied constraint if the constraint is not satisfied by the topic path.
  • invalid update stream if the update stream has been invalidated.
  • cluster repartition if the cluster was repartitioning.
  • session security if the calling session does not have the MODIFY_TOPIC or UPDATE_TOPIC permission for path.
  • session closed if the session is closed.
Parameters
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and result will be non-nil. The completion handler will be called asynchronously on the main dispatch queue.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf completionHandler is nil.
Since
6.3