Package 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 customised 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). Topic specifications can be created using Diffusion.newTopicSpecification(TopicType) and further customised 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",
         Diffusion.newTopicSpecification(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(String, TopicSpecification) 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 removeTopics(com.pushtechnology.diffusion.client.topics.TopicSelector) 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 stream 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
Author:
DiffusionData Limited