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

Introduction

The Topic Control feature provides a client session with the ability to manage topics.

This feature allows a session to manage topics. It provides the following capabilities:

  1. Adding and removing topics.
  2. Missing topic notifications — listening for requests to subscribe to topics that do not exist thus allowing dynamic topic creation on demand.

Topics

The Diffusion server stores data in topics. Each topic is bound to a topic path in the topic tree, and may have a current value. Sessions can subscribe to topics. Updates to topic values are broadcast to subscribing sessions. There are several types of topic. The topic type determines the type of the data values a topic publishes to subscribers.

Adding topics

Creating topics

The simplest way to create a topic is to call addTopicWithPath:type:completionHandler: (PTDiffusionTopicControlFeature), supplying a topic type. For example, to create a JSON topic bound to the topic path foo:


    [topicControl addTopicWithPath:@"foo"
                            type:PTDiffusionTopicType_JSON
                completionHandler:^(PTDiffusionAddTopicResult *const result, NSError *const error)
    {
        ...
    }];

 

Success or failure is reported asynchronously through the completionHandler arguments.

The nature of a topic depends primarily on its topic type, but can be customized using topic properties. Some types of topic cannot be created without supplying mandatory topic properties. Topic properties can be supplied in a topic specification using addTopicWithPath:specification:completionHandler:. Topic specifications can be created using `PTDiffusionTopicSpecification#initWithType:} and further customized with builder methods. For example, to create a JSON topic bound to the topic path foo with the validate values property set to true:

 
    PTDiffusionTopicSpecification *topicSpecification =
        [PTDiffusionTopicSpecification alloc] initWithType:PTDiffusionTopicType_JSON
                                                properties:@{validateValuesPropertyKey (PTDiffusionTopicSpecification) : truePropertyValue (PTDiffusionTopicSpecification)}];
    [topicControl addTopicWithPath:@"foo"
                     specification:topicSpecification
                 completionHandler:^(PTDiffusionAddTopicResult *const result, NSError *const error)
    {
        ...
    }];
 
 

See PTDiffusionTopicSpecification for details of the available topic properties and their effects on the different types of topic.

Topic creation is idempotent. If addTopicWithPath:specification:completionHandler: is called and there is already a topic bound to path with a topic specification equal to specification, the call will complete normally with an exists (PTDiffusionAddTopicResult) result. However, if there is a topic bound to path with a different topic specification, the completionHandler will return an error.

Removing topics

Topics can be removed using removeTopicsWithTopicSelectorExpression. Only those selected topics that the caller has modifyTopic (PTDiffusionPathPermission) permission to will be removed, any others will remain.

Topics can also be automatically removed according to a removal criteria specified using the removalPropertyKey (PTDiffusionTopicSpecification) topic property.

Managing topic tree hierarchies

A topic can be bound to any path in the topic tree namespace. The only restriction is that two topics can not have the same path.

In the following example a topic can be created with the path A/B/foo even though there are no topics with path A or A/B:

 
    [topicControl addTopicWithPath:@"A/B/foo"
                              type:PTDiffusionTopicType_JSON
                 completionHandler:^(PTDiffusionAddTopicResult *const result, NSError *const error)
    {
        ...
    }];
 
 

Topics bound to the paths A or A/B can be created later.

Topics can be removed without affecting the topics subordinate to them in the topic tree using removeDiscreteWithTopicSelectorExpression:completionHandler: providing a path topic selector. By using the // topic selector qualifier it is possible to remove a topic and all of its descendant topics, that is to remove whole topic tree branches.

Access control

To add or remove a topic, a session needs modifyTopic (PTDiffusionPathPermission) permission for the topic path. When removing topics with a topic selector that matches more than one topic, only topics with paths for which the session has modifyTopic (PTDiffusionPathPermission) permission will be removed.

To successfully register a missing topic handler using addMissingTopicHandler:forTopicPath:completionHandler: (PTDiffusionTopicControlFeature), the session needs registerHandler (PTDiffusionGlobalPermission) permission.

Accessing the feature

The Topic Control feature for a session can be obtained from the session's PTDiffusionSession::topicControl property.

See Also
PTDiffusionSession
Since
5.7
Inheritance diagram for PTDiffusionTopicControlFeature:
PTDiffusionFeature

Instance Methods

(void) - addMissingTopicHandler:forTopicPath:completionHandler:
 
(void) - addTopicWithPath:type:completionHandler:
 
(void) - addTopicWithPath:specification:completionHandler:
 
(void) - removeDiscreteWithTopicSelectorExpression:completionHandler:
 
(void) - removeTopicsWithTopicSelectorExpression:completionHandler:
 

Additional Inherited Members

- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (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 using a topic selector that matches no existing topics. This allows a control client session to be notified when another session requests a topic that does not exist.

A session 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.

Parameters
handlerThe handler to use for the topic tree branch identified by the given topicPath (unless overridden by a handler registered against a more specific branch).
topicPathIdentifies a branch of the topic tree.
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 the registration argument will not be nil. The completion handler will be called asynchronously on the main dispatch queue.
Note
If the session is closing or closed when this method is called, the completion handler block will be called with an error, while the missing topic handler will receive no messages.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
5.7
- (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.

Parameters
pathThe full path of the topic to be created.
specificationDefines the topic to be created.
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.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or value has been supplied for a topic type that is not stateful.
Since
6.1
- (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.

Parameters
pathThe full path of the topic to be created.
typeThe type of topic to be created.
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.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or value has been supplied for a topic type that is not stateful.
Since
6.1
- (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.

Parameters
expressionThe topic selector expression to be evaluated by the server.
completionHandlerBlock 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.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
5.9
Deprecated:
since 6.6. Use removeTopicsWithTopicSelectorExpression instead.
- (void) removeTopicsWithTopicSelectorExpression: (NSString *)  expression
completionHandler: (PTDiffusionTopicRemovalResult *_Nullable)  result
(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.

Parameters
expressionThe topic selector expression to be evaluated by the server.
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. result provides the number of topics removed via removedCount.

The completion handler will be called asynchronously on the main dispatch queue.

Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.6