In some cases an application may have multiple components which subscribe and unsubscribe to topics using the same session.

An application component can use a topic selection scope to manage a set of selectors that is unaffected by unsubscriptions performed by other application components. The session will be subscribed to all topics with paths matching a selector in any scope. The unsubscribe operation removes a selector from specific scopes.

A scope may be specified to a subscribe or unsubscribe method, indicating that the selection only applies to that scope. The server manages scopes to ensure that unsubscriptions applied to one scope do not affect another.

Scope names are case sensitive. A scope name may not begin with the character $ as this is reserved for internal use.

Unsubscription using a wildcard selector that indicates all topics (such as ?.*//) effectively removes the scope.

An application can request unsubscription from all scopes using unsubscribeAllScopes.

The DEFAULT_SELECTION_SCOPE ("") is used for all methods that do not explicitly specify a scope. This maintains backwards compatibility but it is not advised to combine the use of named scopes with the default scope.

For example, if our application has a single session which is used by multiple components:

final Session session = Diffusion.sessions().open(serverUrl);
final Topics topics = session.feature(Topics.class);

In component A we subscribe to a topic with a specified scope:

topics.subscribe("my/topic/path", "scopeA");

Elsewhere in the application component B subscribes to the same topic with its own scope:

topics.subscribe("my/topic/path", "scopeB");

Component A no longer needs the subscription and unsubscribes:

topics.unsubscribe("my/topic/path", "scopeA");

In this scenario component B is still subscribed. When component B unsubscribes (or unsubscribeAllScopes is called) the session is unsubscribed.

topics.unsubscribe("my/topic/path", "scopeB");

It should be noted that value streams are managed independently of subscriptions. Unsubscribing with a scope will not prevent a component from receiving value updates from a registered stream. As long as any scope in the application has a subscription to a topic, the session will receive updates for that topic and streams that select that topic will receive those updates. To stop updates for a selection the stream should be removed. For more information see Using streams for subscription.

Subscription Control

The SubscriptionControl feature can be used to manage subscriptions on behalf of clients and as such can manage the selection scopes that an application may be using. It also allows control clients to get a representation of the current active scopes. For example:

Subscribe a client to a topic with a scope:

subscriptionControl.subscribe(session.getSessionID(), "my/topic/path", "scopeA");

Subscribe clients to a topic with a scope using a session filter:

subscriptionControl.subscribeByFilter("$Principal is 'client'", "my/topic/path", "scopeA");

Get all active scopes for a session:

subscriptionControl.getTopicSelections(session.getSessionId());

When managing selection scopes in this way there is a need for collaborative design of the application to ensure consistent use of scopes across clients and control clients.