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

Interface SubscriptionControl

All Superinterfaces:

Feature

public interface SubscriptionControl
extends Feature

This feature allows a session to subscribe or unsubscribe other sessions to topics, on a single server or across a cluster.

Requests to subscribe sessions to topics can be submitted at any time even if the topics do not exist at the server. Topic selectors are used on subscription to match against topics at the server. The session will become subscribed to any topics that exist at the server that match the selector (unless they are already subscribed, or the session has insufficient permission). The subscription request is also retained at the server so that if any newly created topics match the selector, the session will then become subscribed to it (unless a subsequent unsubscription cancels it).

Specific sessions (anywhere in a cluster) may be subscribed/unsubscribed if the SessionId is known.

Subscriptions may also be requested using 'session filters' (see Session for a full description of session filters), where all sessions (anywhere in a cluster) that satisfy a particular filter expression will be subscribed/unsubscribed. The filter is only evaluated once against the current sessions that exist at the time - it is not retained and applied to any sessions that are created later. In order to be notified of new sessions as they are created session event listeners can be used and those sessions subscribed as required based upon their session properties.

This feature also provides the ability to query the topic selections of another session.

Access control

To directly subscribe other sessions to topics, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the topic selector used for subscription. The subscribed sessions will only be subscribed to matching topics for which they have READ_TOPIC permission.

To directly unsubscribe other sessions, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the topic selector used for unsubscription.

Getting the topic selections for a specified session requires VIEW_SESSION permission.

Accessing the feature

This feature may be obtained from a session as follows:

 
 SubscriptionControl subsControl = session.feature(SubscriptionControl.class);
 
 

Since:

5.0

Author:

DiffusionData Limited

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	SubscriptionControl.SubscriptionByFilterResult	Result used by CompletableFuture variants of subscribeByFilter and unsubscribeByFilter.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Map<String,List<TopicSelection>>>	getTopicSelections(SessionId sessionId)	Returns a map of the current topic selection state for a specified session, keyed on topic selection scope.
default CompletableFuture<?>	subscribe(SessionId sessionId, TopicSelector topics)	Subscribe another session to topics.
CompletableFuture<?>	subscribe(SessionId sessionId, TopicSelector topics, String scope)	Subscribe another session to topics.
default CompletableFuture<?>	subscribe(SessionId sessionId, String topics)	Subscribe another session to topics.
CompletableFuture<?>	subscribe(SessionId sessionId, String topics, String scope)	Subscribe another session to topics.
default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	subscribeByFilter(String filter, TopicSelector topics)	Subscribe sessions that satisfy a given session filter to topics.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	subscribeByFilter(String filter, TopicSelector topics, String scope)	Subscribe sessions that satisfy a given session filter to topics.
default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	subscribeByFilter(String filter, String topics)	Subscribe sessions that satisfy a given session filter to topics.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	subscribeByFilter(String filter, String topics, String scope)	Subscribe sessions that satisfy a given session filter to topics.
default CompletableFuture<?>	unsubscribe(SessionId sessionId, TopicSelector topics)	Unsubscribe another session from topics.
CompletableFuture<?>	unsubscribe(SessionId sessionId, TopicSelector topics, String scope)	Unsubscribe another session from topics.
default CompletableFuture<?>	unsubscribe(SessionId sessionId, String topics)	Unsubscribe another session from topics.
CompletableFuture<?>	unsubscribe(SessionId sessionId, String topics, String scope)	Unsubscribe another session from topics.
CompletableFuture<?>	unsubscribeAllScopes(SessionId sessionId, TopicSelector topics)	Unsubscribe topics from all topic selection scopes.
CompletableFuture<?>	unsubscribeAllScopes(SessionId sessionId, String topics)	Unsubscribe another session from topics for all topic selection scopes.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeAllScopesByFilter(String filter, TopicSelector topics)	Unsubscribe sessions that satisfy a given session filter from topics for all scopes.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeAllScopesByFilter(String filter, String topics)	Unsubscribe sessions that satisfy a given session filter from topics for all scopes.
default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeByFilter(String filter, TopicSelector topics)	Unsubscribe sessions that satisfy a given session filter from topics.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeByFilter(String filter, TopicSelector topics, String scope)	Unsubscribe sessions that satisfy a given session filter from topics.
default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeByFilter(String filter, String topics)	Unsubscribe sessions that satisfy a given session filter from topics.
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>	unsubscribeByFilter(String filter, String topics, String scope)	Unsubscribe sessions that satisfy a given session filter from topics.

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

getSession

Method Details

subscribe

default CompletableFuture<?> subscribe(SessionId sessionId,
 String topics)

Subscribe another session to topics.

This is equivalent to calling subscribe(SessionId, String, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

subscribe

CompletableFuture<?> subscribe(SessionId sessionId,
 String topics,
 String scope)
                        throws IllegalArgumentException

Subscribe another session to topics.

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

Parameters:

sessionId - identifies the session to subscribe

topics - the topics to subscribe to specified as a TopicSelector expression

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the subscription request.

If the subscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is not a valid selector expression

Since:

6.12

subscribe

default CompletableFuture<?> subscribe(SessionId sessionId,
 TopicSelector topics)

Subscribe another session to topics.

This is equivalent to calling subscribe(SessionId, TopicSelector, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

subscribe

CompletableFuture<?> subscribe(SessionId sessionId,
 TopicSelector topics,
 String scope)

Subscribe another session to topics.

New subscriptions will be established for existing topics that match the provided topic selector and for which the subscribed session has READ_TOPIC permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have SELECT_TOPIC permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters:

sessionId - identifies the session to subscribe

topics - identifies the topics to subscribe to

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the subscription request.

If the subscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

unsubscribe

default CompletableFuture<?> unsubscribe(SessionId sessionId,
 String topics)

Unsubscribe another session from topics.

This is equivalent to calling unsubscribe(SessionId, String, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

unsubscribe

CompletableFuture<?> unsubscribe(SessionId sessionId,
 String topics,
 String scope)
                          throws IllegalArgumentException

Unsubscribe another session from topics.

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

Parameters:

sessionId - identifies the session to unsubscribe

topics - the topics to unsubscribe specified as a TopicSelector expression

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is not a valid selector expression

Since:

6.12

unsubscribe

default CompletableFuture<?> unsubscribe(SessionId sessionId,
 TopicSelector topics)

Unsubscribe another session from topics.

This is equivalent to calling unsubscribe(SessionId, TopicSelector, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

unsubscribe

CompletableFuture<?> unsubscribe(SessionId sessionId,
 TopicSelector topics,
 String scope)

Unsubscribe another session from topics.

Parameters:

sessionId - identifies the session to unsubscribe

topics - the topics to unsubscribe from

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

subscribeByFilter

default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
 String topics)

Subscribe sessions that satisfy a given session filter to topics.

This is equivalent to calling subscribeByFilter(String, String, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

subscribeByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
 String topics,
 String scope)
                                                                             throws IllegalArgumentException

Subscribe sessions that satisfy a given session filter to topics. In a clustered environment the filter will be applied to all servers in the cluster.

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

Parameters:

filter - the session filter expression

topics - the topics to subscribe to specified as a TopicSelector expression

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the subscription request.

If the subscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is not a valid selector expression

Since:

6.12

subscribeByFilter

default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
 TopicSelector topics)

Subscribe sessions that satisfy a given session filter to topics.

This is equivalent to calling subscribeByFilter(String, TopicSelector, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

subscribeByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
 TopicSelector topics,
 String scope)

Subscribe sessions that satisfy a given session filter to topics. In a clustered environment the filter will be applied to all servers in the cluster.

For each session that matches the filter, new subscriptions will be established for existing topics that match the provided topic selector and for which the sessions has READ_TOPIC permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have SELECT_TOPIC permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters:

filter - the session filter expression

topics - the topics to subscribe to specified as a TopicSelector expression

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the subscription request.

If the subscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

unsubscribeByFilter

default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
 String topics)

Unsubscribe sessions that satisfy a given session filter from topics.

This is equivalent to calling unsubscribeByFilter(String, String, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

unsubscribeByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
 String topics,
 String scope)
                                                                               throws IllegalArgumentException

Unsubscribe sessions that satisfy a given session filter from topics. In a clustered environment the filter will be applied to all servers in the cluster.

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

Parameters:

filter - the session filter expression

topics - the topics to unsubscribe from specified as a TopicSelector expression

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is not a valid selector expression

Since:

6.12

unsubscribeByFilter

default CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
 TopicSelector topics)

Unsubscribe sessions that satisfy a given session filter from topics.

This is equivalent to calling unsubscribeByFilter(String, TopicSelector, String) specifying the default selection scope.

Since:

6.0

See Also:

• Topic Selection Scopes

unsubscribeByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
 TopicSelector topics,
 String scope)

Unsubscribe sessions that satisfy a given session filter from topics. In a clustered environment the filter will be applied to all servers in the cluster.

Parameters:

filter - the session filter expression

topics - the topics to unsubscribe from specified as a TopicSelector

scope - specifies the scope of the selection. See Topic Selection Scopes

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

unsubscribeAllScopes

CompletableFuture<?> unsubscribeAllScopes(SessionId sessionId,
 String topics)
                                   throws IllegalArgumentException

Unsubscribe another session from topics for all topic selection scopes.

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

Parameters:

sessionId - identifies the session to unsubscribe

topics - the topics to unsubscribe from

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is an invalid topic selector expression

Since:

6.12

unsubscribeAllScopes

CompletableFuture<?> unsubscribeAllScopes(SessionId sessionId,
 TopicSelector topics)

Unsubscribe topics from all topic selection scopes.

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests and will apply to all scopes in use.

Parameters:

sessionId - identifies the session to unsubscribe

topics - the topics to unsubscribe from

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

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

• PermissionsException – if the calling session does not have MODIFY_SESSION permission and SELECT_TOPIC permission for the selector expression;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

unsubscribeAllScopesByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeAllScopesByFilter(String filter,
 String topics)
                                                                                        throws IllegalArgumentException

Unsubscribe sessions that satisfy a given session filter from topics for all scopes. In a clustered environment the filter will be applied to all servers in the cluster.

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

Parameters:

filter - the session filter expression

topics - the topics to unsubscribe from specified as a TopicSelector expression

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Throws:

IllegalArgumentException - if topics is not a valid selector expression

Since:

6.12

unsubscribeAllScopesByFilter

CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeAllScopesByFilter(String filter,
 TopicSelector topics)

Unsubscribe sessions that satisfy a given session filter from topics for all scopes. In a clustered environment the filter will be applied to all servers in the cluster.

Parameters:

filter - the session filter expression

topics - the topics to unsubscribe from specified as a TopicSelector

Returns:

a CompletableFuture that completes when the server has processed the unsubscription request.

If the unsubscription was accepted, the CompletableFuture will complete successfully with a SubscriptionControl.SubscriptionByFilterResult.

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

• InvalidFilterException – if the filter is invalid;
• PermissionsException – if the calling session does not have MODIFY_SESSION permission as well as SELECT_TOPIC permission for the selector expression;
• SessionClosedException – if the session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12

getTopicSelections

CompletableFuture<Map<String,List<TopicSelection>>> getTopicSelections(SessionId sessionId)

Returns a map of the current topic selection state for a specified session, keyed on topic selection scope.

Each scope will have an ordered list of selections and/or deselections.

The server conflates selections, so if there has been a selection that is later rendered redundant by a deselection it will not be present. A scope that has been used but fully deselected will therefore not be present in the map and therefore no entry will have an empty list.

If the session has no current selections the map will be empty.

Parameters:

sessionId - identifies the session to return topic selections for

Returns:

a CompletableFuture that completes when a response is received from the server with the results of the operation.

If the task completes successfully, the CompletableFuture result will be a map of an ordered List of TopicSelections keyed on scope. If the default scope is in use the key will be Topics.DEFAULT_SELECTION_SCOPE.

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

• PermissionsException – if the calling session does not have VIEW_SESSION permission;
• NoSuchSessionException – if there is no session with the given sessionId on the current server or on any other servers in a clustered environment;;
• SessionClosedException – if the current session is closed.
• ClusterRoutingException – if the operation failed due to a transient cluster error;

Since:

6.12