Diffusion Apple API
6.2.7
Unified Client Library for iOS, tvOS and OS X / macOS
|
The Topic Control feature provides a client session with the ability to manage topics.
The Topic Control feature for a session can be obtained from the session's topicControl
property.
Instance Methods | |
(void) | - addMissingTopicHandler:forTopicPath:completionHandler: |
(void) | - addTopicWithPath:type:completionHandler: |
(void) | - addTopicWithPath:specification:completionHandler: |
(void) | - addTopicEventListener:forTopicPath:completionHandler: |
(void) | - removeDiscreteWithTopicSelectorExpression:completionHandler: |
(void) | - removeTopicsWithSessionForTopicPath:delegate:completionHandler: |
Instance Methods inherited from PTDiffusionFeature | |
(instancetype) | - NS_UNAVAILABLE |
Additional Inherited Members | |
Class Methods inherited from PTDiffusionFeature | |
(instancetype) | + NS_UNAVAILABLE |
Properties inherited from PTDiffusionFeature | |
PTDiffusionSession * | session |
- (void) addMissingTopicHandler: | (id< PTDiffusionMissingTopicHandler >) | handler | |
forTopicPath: | (NSString *) | topicPath | |
completionHandler: | (PTDiffusionTopicTreeRegistration *_Nullable) | registration | |
(NSError *_Nullable error) | completionHandler | ||
Register a handler of requests for a branch of the topic tree.
The provided handler is called when a client subscribes or fetches using a topic selector that matches no existing topics. This allows a control client to intercede when another session requests a topic that does not exist. The control client may use any of the add topic methods to create the topic, take some other action, or do nothing, before allowing the client operation to proceed by calling proceed. Alternatively, the control client can call cancel to discard the request.
A control client can register multiple handlers, but may only register a single handler for a given topic path. A handler will only be called for topic selectors with a path prefix that starts with or is equal to topicPath. If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.
handler | The handler to use for the topic tree branch identified by the given topicPath (unless overridden by a handler registered against a more specific branch). |
topicPath | Identifies a branch of the topic tree. |
completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil . |
- (void) addTopicEventListener: | (id< PTDiffusionTopicEventListener >) | listener | |
forTopicPath: | (NSString *) | topicPath | |
completionHandler: | (PTDiffusionTopicTreeRegistration *_Nullable) | registration | |
(NSError *_Nullable error) | completionHandler | ||
Register a listener to receive topic events for a branch of the topic tree.
This allows a client to receive different events for topics. These events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers, or when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to it's previous state.
Each control session may register a single handler for a branch.
listener | Specifies the listener for the specified branch (unless overriden by a listener registered against a more specific branch). |
topicPath | Identifies a branch of the topic tree. |
completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil . |
subscriptions < n for
condition. The removal topic property is fully cluster aware. This method will be removed in a future release.- (void) addTopicWithPath: | (NSString *) | path | |
specification: | (PTDiffusionTopicSpecification *) | specification | |
completionHandler: | (PTDiffusionAddTopicResult *_Nullable) | result | |
(NSError *_Nullable error) | completionHandler | ||
Send a request to the server to add a topic.
The topic will be initialized with the given value, if specified non-nil
, during creation and therefore the value must be compatible with the topic type.
path | The full path of the topic to be created. |
specification | Defines the topic to be created. |
completionHandler | Block 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 ne non-nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil or value has been supplied for a topic type that is not stateful. |
- (void) addTopicWithPath: | (NSString *) | path | |
type: | (PTDiffusionTopicType) | type | |
completionHandler: | (PTDiffusionAddTopicResult *_Nullable) | result | |
(NSError *_Nullable error) | completionHandler | ||
Send a request to the server to add a topic.
This is a convenience method which creates the topic with default details for the given type.
path | The full path of the topic to be created. |
type | The type of topic to be created. |
completionHandler | Block 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 ne non-nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil or value has been supplied for a topic type that is not stateful. |
- (void) removeDiscreteWithTopicSelectorExpression: | (NSString *) | expression | |
completionHandler: | (NSError *_Nullable error) | completionHandler | |
Send a request to remove one or more topics.
All topics that match the provided topic selector that the caller has permission to remove will be removed.
The selector's descendant pattern qualifier (a trailing /
or //
), can be used to remove descendant topics. If a single /
qualifier is specified, all descendants of the matched topic paths will be removed. If //
is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.
expression | The topic selector expression to be evaluated by the server. |
completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil . |
- (void) removeTopicsWithSessionForTopicPath: | (NSString *) | topicPath | |
delegate: | (id< PTDiffusionTopicTreeRegistrationDelegate >) | delegate | |
completionHandler: | (PTDiffusionTopicTreeRegistration *_Nullable) | registration | |
(NSError *_Nullable error) | completionHandler | ||
Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.
The server will remove the topics if this session is closed. If several client sessions request removal of the same branch, the topics will not be removed until the last session is closed.
For example, suppose two client sessions both call register expression "a/b". When both sessions are closed, either explicitly or by the server, the topic a/b
and all of its descendants will be removed. This method is typically used by a client that has added one or more topics to tidy up and remove the topics if it is ever disconnected from the server or otherwise fails.
The server will reject a request if the topicPath conflicts with existing registrations. Different sessions can call this method for the same topic path, but not for topic paths above or below existing registrations on the same branch of the topic tree.
The last session to close must have MODIFY_TOPIC permission for topicPath. If this is not the case, none of the topic or its descendants will be removed.
topicPath | Identifies a branch of the topic tree. This topic and its descendants will be removed if the action is executed. |
delegate | The delegate to be informed of lifecycle events in respect of this registration. |
completionHandler | Block to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil . The completion handler will be called asynchronously on the main dispatch queue. |
NSInvalidArgumentException | If any argument is nil . |
when this session closes remove "?\<topicPath\>//"
. To achieve a dependency upon more than one session, a condition specifying a principal name or some other session property could be used. This method will be removed in a future release.