com.pushtechnology.diffusion.client.features.control.topics

Interface TopicControl

All Superinterfaces:

Feature

public interface TopicControl
extends Feature

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.
3) Topic event listeners — listening for topic events, such as the number of subscribers to a topic changing from zero to greater than zero or from greater than zero to zero.

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 addTopic(String, TopicType), supplying a topic type. For example, to create a JSON topic bound to the topic path foo:

 CompletableFuture<AddTopicResult%gt; result =
     topicControl.addTopic("foo", TopicType.JSON);
 

Success or failure is reported asynchronously through the CompletableFuture result.

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 addTopic(String, TopicSpecification, AddCallback). Topic specifications can be created using newSpecification(TopicType) 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:

 CompletableFuture<AddTopicResult> result =
     topicControl.addTopic(
         "foo",
         topicControl.newSpecification(TopicType.JSON)
             .withProperty(TopicSpecification.VALIDATE_VALUES, "true"));
 

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

Topic creation is idempotent. If addTopic(path, specification) 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 TopicControl.AddTopicResult.EXISTS result. However, if there is a topic bound to path with a different topic specification, the call will complete exceptionally with an TopicControl.ExistingTopicException.

Removing topics

Topics can be removed using removeTopics(TopicSelector). Only those selected topics that the caller has MODIFY_TOPIC permission to will be removed, any others will remain.

Topics can also be automatically removed according to a removal criteria specified using the REMOVAL 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.addTopic("A/B/foo", TopicType.JSON);
 

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 remove(java.lang.String, com.pushtechnology.diffusion.client.features.control.topics.TopicControl.RemovalCallback) 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 MODIFY_TOPIC 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 MODIFY_TOPIC permission will be removed.

To register a missing topic handler the session needs REGISTER_HANDLER permission.

Accessing the feature

This feature may be obtained from a session as follows:

 TopicControl topicControl = session.feature(TopicControl.class);
 

Since:

5.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TopicControl.AddCallback Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static interface	TopicControl.AddContextCallback<C> Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static class	TopicControl.AddTopicException Exception thrown to report a failure to add a topic.
static class	TopicControl.AddTopicResult Used to report the result of adding a topic.
static class	TopicControl.ExistingTopicException Exception thrown to report a topic could not be added because an existing topic with a different specification is bound to the topic path.
static class	TopicControl.IncompatibleExistingTopicException Exception thrown to report that a topic exists at the same path that is managed by a component that has exclusive control over the topic.
static class	TopicControl.IncompatibleTopicException Exception thrown to report a topic could not be added because there is an existing topic that is incompatible with the request.
static class	TopicControl.InvalidTopicPathException Exception thrown to report a topic could not be added because the topic path supplied is invalid.
static class	TopicControl.InvalidTopicSpecificationException Exception thrown to report a topic could not be added because the specification is invalid.
static interface	TopicControl.MissingTopicHandler Deprecated. since 6.7 Use TopicControl.MissingTopicNotificationStream instead.
static interface	TopicControl.MissingTopicNotification Notification that a session has made a subscription request using a selector that does not match any topics.
static interface	TopicControl.MissingTopicNotificationStream Stream called when a session subscribes using a topic selector that matches no topics.
static interface	TopicControl.RemovalCallback Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static interface	TopicControl.RemovalContextCallback<C> Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
static class	TopicControl.TopicLicenseLimitException Exception thrown to report a topic could not be added because a licence limit has been exceeded.
static interface	TopicControl.TopicRemovalResult Reports the number of topics removed by a call to removeTopics(com.pushtechnology.diffusion.client.topics.TopicSelector).

Method Summary

Modifier and Type	Method and Description
void	addMissingTopicHandler(String topicPath, TopicControl.MissingTopicHandler handler) Deprecated. since 6.7 Prefer the CompletableFuture-based alternative addMissingTopicHandler(String, MissingTopicNotificationStream) since it provides better error reporting.
CompletableFuture<Registration>	addMissingTopicHandler(String topicPath, TopicControl.MissingTopicNotificationStream handler) Register a TopicControl.MissingTopicNotificationStream to handle requests for a branch of the topic tree.
CompletableFuture<TopicControl.AddTopicResult>	addTopic(String topicPath, TopicSpecification specification) Request creation of a topic.
<C> void	addTopic(String topicPath, TopicSpecification specification, C context, TopicControl.AddContextCallback<C> callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
void	addTopic(String topicPath, TopicSpecification specification, TopicControl.AddCallback callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
CompletableFuture<TopicControl.AddTopicResult>	addTopic(String topicPath, TopicType topicType) Request creation of a topic.
TopicSpecification	newSpecification(TopicType topicType) Deprecated. since 6.7 Use Diffusion.newTopicSpecification which can be imported with a static import, instead.
<C> void	remove(String topicSelector, C context, TopicControl.RemovalContextCallback<C> callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
void	remove(String topicSelector, TopicControl.RemovalCallback callback) Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
CompletableFuture<TopicControl.TopicRemovalResult>	removeTopics(String topicSelector) Send a request to remove one or more topics.
CompletableFuture<TopicControl.TopicRemovalResult>	removeTopics(TopicSelector topicSelector) Send a request to remove one or more topics.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

getSession

Method Detail

newSpecification

@Deprecated
TopicSpecification newSpecification(TopicType topicType)

Deprecated. since 6.7

Use Diffusion.newTopicSpecification which can be imported with a static import, instead.

Create a new TopicSpecification for a given topic type.

Parameters:

topicType - the topic type

Returns:

a new immutable specification with no properties set. New specifications with different properties can be produced using the withProperty or withProperties methods of the provided specification.

Since:

5.7

addTopic

CompletableFuture<TopicControl.AddTopicResult> addTopic(String topicPath,
                                                        TopicType topicType)

Request creation of a topic.

This is a convenience method that is equivalent to:

 topicControl.addTopic(
     topicPath,
     topicControl.newSpecification(topicType));
 

Parameters:

topicPath - the topic path to which the topic will be bound

topicType - the type of topic to be created

Returns:

a CompletableFuture that completes when a response is received from the server.

If the task completes successfully, the CompletableFuture result will be indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to at topicPath.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• TopicControl.ExistingTopicException – a topic is bound to topicPath with a different topic specification;
• TopicControl.IncompatibleExistingTopicException – an incompatible topic already exists at topicPath;
• 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;
• TopicControl.AddTopicException – the topic could not be created for some reason other than those specified above;
• PermissionsException – the calling session does not have MODIFY_TOPIC permission for topicPath;
• SessionClosedException – the session is closed.

Since:

6.0

addTopic

CompletableFuture<TopicControl.AddTopicResult> addTopic(String topicPath,
                                                        TopicSpecification specification)

Request creation of a topic.

Parameters:

topicPath - the topic path to which the topic will be bound

specification - defines the topic to be created. A specification can be created using newSpecification(TopicType).

Returns:

a CompletableFuture that completes when a response is received from the server.

If the task completes successfully, the CompletableFuture result will be indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to at topicPath.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• TopicControl.ExistingTopicException – a topic is bound to topicPath with a different topic specification;
• TopicControl.IncompatibleExistingTopicException – an incompatible topic already exists at topicPath;
• TopicControl.InvalidTopicPathException – topicPath is not a valid topic path;
• TopicControl.InvalidTopicSpecificationException – the specification is invalid;
• 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;
• TopicControl.AddTopicException – the topic could not be created for some reason other than those specified above;
• PermissionsException – the calling session does not have MODIFY_TOPIC permission for topicPath;
• SessionClosedException – the session is closed.

Since:

6.0

addTopic

@Deprecated
<C> void addTopic(String topicPath,
                              TopicSpecification specification,
                              C context,
                              TopicControl.AddContextCallback<C> callback)

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Version of addTopic(String, TopicSpecification, AddCallback) that allows a user defined context to be provided.

Type Parameters:

C - the context object type

Parameters:

topicPath - the topic path to which the topic will be bound

specification - defines the topic to be created. A specification can be created using newSpecification(TopicType).

context - an object passed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including null

callback - called with the result

Since:

5.7

addTopic

@Deprecated
void addTopic(String topicPath,
                          TopicSpecification specification,
                          TopicControl.AddCallback callback)

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Send a request to the server to add a topic.

Parameters:

topicPath - the topic path to which the topic will be bound

specification - defines the topic to be created. A specification can be created using newSpecification(TopicType).

callback - called with the result

Since:

5.7

removeTopics

CompletableFuture<TopicControl.TopicRemovalResult> removeTopics(TopicSelector topicSelector)

Send a request to remove one or more topics.

All topics that match the provided topicSelector 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:

topicSelector - specifies the topics to remove

Returns:

a CompletableFuture that completes when a response is received from the server.

If the task completes successfully, the CompletableFuture result will bear a TopicControl.TopicRemovalResult. This provides the number of topics removed by calling TopicControl.TopicRemovalResult.getRemovedCount().

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionClosedException – the session is closed.

Since:

6.0

removeTopics

CompletableFuture<TopicControl.TopicRemovalResult> removeTopics(String topicSelector)
                                                         throws IllegalArgumentException

Send a request to remove one or more topics.

This is equivalent to calling removeTopics(TopicSelector) with a selector parsed using TopicSelectors.parse(String).

Parameters:

topicSelector - a topic selector expression specifying the topics to remove.

Returns:

a CompletableFuture that completes when a response is received from the server.

If the task completes successfully, the CompletableFuture result will bear a TopicControl.TopicRemovalResult. This provides the number of topics removed by calling TopicControl.TopicRemovalResult.getRemovedCount().

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• SessionClosedException – the session is closed.

Throws:

IllegalArgumentException - if topicSelector is an invalid topic selector expression

Since:

6.0

remove

@Deprecated
void remove(String topicSelector,
                        TopicControl.RemovalCallback callback)
                 throws IllegalArgumentException

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Send a request to remove one or more topics.

All topics that match the provided topicSelector 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:

topicSelector - a topic selector expression specifying the topics to remove

callback - called to notify request completed

Throws:

IllegalArgumentException - if topicSelector is an invalid topic selector expression

Since:

5.9

remove

@Deprecated
<C> void remove(String topicSelector,
                            C context,
                            TopicControl.RemovalContextCallback<C> callback)
                     throws IllegalArgumentException

Deprecated. since 6.7

Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Version of remove(String, RemovalCallback) that allows a user defined context to be provided.

Type Parameters:

C - the context object type

Parameters:

topicSelector - a topic selector expression specifying the topics to remove

context - an object passed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including null

callback - called to notify request completed

Throws:

IllegalArgumentException - if topicSelector is an invalid topic selector expression

Since:

5.9

addMissingTopicHandler

CompletableFuture<Registration> addMissingTopicHandler(String topicPath,
                                                       TopicControl.MissingTopicNotificationStream handler)

Register a TopicControl.MissingTopicNotificationStream to handle requests for a branch of the topic tree.

The provided handler is called when a session 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. If there is already a handler registered for the topic path the operation will fail with a HandlerConflictException. 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.

Prefer this method to the callback-based alternative addMissingTopicHandler(String, MissingTopicHandler) since it provides better error reporting.

Parameters:

topicPath - identifies a branch of the topic tree

handler - the handler to use for notifying topics at or below the topicPath (unless there is a handler registered for a more specific topic path)

Returns:

a CompletableFuture that completes when the handler is registered with the server.

If registration was successful, the CompletableFuture will complete successfully with a Registration which can be used to unregister the handler.

Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

• HandlerConflictException – if the session has already registered a missing topic handler for topicPath;
• PermissionsException – if the session does not have REGISTER_HANDLER permission;
• SessionClosedException – if the session is closed.

Since:

6.0

addMissingTopicHandler

@Deprecated
void addMissingTopicHandler(String topicPath,
                                        TopicControl.MissingTopicHandler handler)

Deprecated. since 6.7

Prefer the CompletableFuture-based alternative addMissingTopicHandler(String, MissingTopicNotificationStream) since it provides better error reporting.

Register a TopicControl.MissingTopicHandler to handle requests for a branch of the topic tree.

The provided handler is called when a session subscribes using a topic selector that matches no existing topics.

A session can register multiple handlers, but may only register a single handler for a given topic path. See onActive. 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:

topicPath - identifies a branch of the topic tree

handler - the handler to use for notifying topics at or below the topicPath (unless there is a handler registered for a more specific topic path)