SubscriptionControl (Diffusion)

All Superinterfaces:

Feature
```
public interface SubscriptionControl
extends Feature
```
This feature allows a session to subscribe or unsubscribe other sessions to topics. It also provides a mechanism for handling requests to subscribe to routing topics (deprecated).
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 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 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 properties listeners can be used and those sessions subscribed as required based upon their session properties.
A handler for routing topics belonging to a branch of the topic tree can be added using addRoutingSubscriptionHandler(). When another session subscribes to one of the routing topics, the handler will be called to determine the appropriate source topic.
Access control
To subscribe other sessions to topics, a session must have MODIFY_SESSION permission, and SELECT_TOPIC permission for the path prefix of the topic selector used for subscription. The subscribed sessions will only be subscribed to matching topics for which they have READ_TOPIC permission.
To unsubscribe other sessions, a session must have MODIFY_SESSION permission.
To register a routing subscription handler the session needs VIEW_SESSION, MODIFY_SESSION and REGISTER_HANDLER permissions.
When handling a subscription request to a routing topic via a routing handler the routing session needs READ_TOPIC permission to both the routing topic being subscribed to and the target topic that is assigned.
Operations that identify sessions using a session filter require the 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

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`SubscriptionControl.RoutingSubscriptionRequest` Deprecated. since 6.7 Routing topics are deprecated. The more powerful `SessionTrees` feature should be used in their place.
`static interface`	`SubscriptionControl.SubscriptionByFilterCallback` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`SubscriptionControl.SubscriptionByFilterContextCallback<C>` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`SubscriptionControl.SubscriptionByFilterResult` Result used by CompletableFuture variants of `subscribeByFilter` and `unsubscribeByFilter`.
`static interface`	`SubscriptionControl.SubscriptionCallback` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`SubscriptionControl.SubscriptionContextCallback<C>` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addRoutingSubscriptionHandler(String topicPath, SubscriptionControl.RoutingSubscriptionRequest.Handler handler)` Deprecated. since 6.7 Routing topics are deprecated. The more powerful `SessionTrees` feature should be used in their place.
`CompletableFuture<Registration>`	`addRoutingSubscriptionHandler(String topicPath, SubscriptionControl.RoutingSubscriptionRequest.RoutingHandler handler)` Deprecated. since 6.7 Routing topics are deprecated. The more powerful `SessionTrees` feature should be used in their place.
`CompletableFuture<?>`	`subscribe(SessionId sessionId, String topics)` Subscribe another session to topics.
`<C> void`	`subscribe(SessionId sessionId, String topics, C context, SubscriptionControl.SubscriptionContextCallback<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`	`subscribe(SessionId sessionId, String topics, SubscriptionControl.SubscriptionCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<?>`	`subscribe(SessionId sessionId, TopicSelector topics)` Subscribe another session to topics.
`<C> void`	`subscribe(SessionId sessionId, TopicSelector topics, C context, SubscriptionControl.SubscriptionContextCallback<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`	`subscribe(SessionId sessionId, TopicSelector topics, SubscriptionControl.SubscriptionCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>`	`subscribeByFilter(String filter, String topics)` Subscribe sessions that satisfy a given session filter to topics.
`<C> void`	`subscribeByFilter(String filter, String topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<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`	`subscribeByFilter(String filter, String topics, SubscriptionControl.SubscriptionByFilterCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>`	`subscribeByFilter(String filter, TopicSelector topics)` Subscribe sessions that satisfy a given session filter to topics.
`<C> void`	`subscribeByFilter(String filter, TopicSelector topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<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`	`subscribeByFilter(String filter, TopicSelector topics, SubscriptionControl.SubscriptionByFilterCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<?>`	`unsubscribe(SessionId sessionId, String topics)` Unsubscribe another session from topics.
`<C> void`	`unsubscribe(SessionId sessionId, String topics, C context, SubscriptionControl.SubscriptionContextCallback<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`	`unsubscribe(SessionId sessionId, String topics, SubscriptionControl.SubscriptionCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<?>`	`unsubscribe(SessionId sessionId, TopicSelector topics)` Unsubscribe another session from topics.
`<C> void`	`unsubscribe(SessionId sessionId, TopicSelector topics, C context, SubscriptionControl.SubscriptionContextCallback<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`	`unsubscribe(SessionId sessionId, TopicSelector topics, SubscriptionControl.SubscriptionCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>`	`unsubscribeByFilter(String filter, String topics)` Unsubscribe sessions that satisfy a given session filter from topics.
`<C> void`	`unsubscribeByFilter(String filter, String topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<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`	`unsubscribeByFilter(String filter, String topics, SubscriptionControl.SubscriptionByFilterCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<SubscriptionControl.SubscriptionByFilterResult>`	`unsubscribeByFilter(String filter, TopicSelector topics)` Unsubscribe sessions that satisfy a given session filter from topics.
`<C> void`	`unsubscribeByFilter(String filter, TopicSelector topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<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`	`unsubscribeByFilter(String filter, TopicSelector topics, SubscriptionControl.SubscriptionByFilterCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.

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

- Method Detail
  - addRoutingSubscriptionHandler
```
@Deprecated
CompletableFuture<Registration> addRoutingSubscriptionHandler(String topicPath,
                                                                          SubscriptionControl.RoutingSubscriptionRequest.RoutingHandler handler)
```
    Deprecated. since 6.7
    Routing topics are deprecated. The more powerful SessionTrees feature should be used in their place.
    
    Adds a handler for routing topics that belong to a branch of the topic tree. When another session subscribes to one of the routing topics, the handler will be called to determine the appropriate source topic.
    For each subscription to the routing topic, the server will select a handler registered for the most specific branch. If multiple handlers are registered for the same branch, the server will select one of them arbitrarily.
    Parameters:
    
    topicPath - identifies the branch of the topic tree to associate the handler with
    
    handler - the handler to use for routing topics at or below the specified path (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 routing subscription handler for topicPath;
    PermissionsException – if the session does not have REGISTER_HANDLER permission;
    PermissionsException – if the session does not have VIEW_SESSION permission;
    PermissionsException – if the session does not have MODIFY_SESSION permission;
    SessionClosedException – if the session is closed.
    Since:
    
    6.0
  - addRoutingSubscriptionHandler
```
@Deprecated
void addRoutingSubscriptionHandler(String topicPath,
                                               SubscriptionControl.RoutingSubscriptionRequest.Handler handler)
```
    Deprecated. since 6.7
    Routing topics are deprecated. The more powerful SessionTrees feature should be used in their place.
    
    Adds a handler for routing topics that belong to a branch of the topic tree. When another session subscribes to one of the routing topics, the handler will be called to determine the appropriate source topic.
    The CompletableFuture-based alternative addRoutingSubscriptionHandler(String, RoutingHandler) should be preferred since it provides better error reporting.
    For each subscription to the routing topic, the server will select a handler registered for the most specific branch. If multiple handlers are registered for the same branch, the server will select one of them arbitrarily.
    
    Parameters:
    
    topicPath - identifies the branch of the topic tree to associate the handler with
    
    handler - the handler to use for routing topics at or below the specified path (unless there is a handler registered for a more specific topic path)
  - subscribe
```
CompletableFuture<?> subscribe(SessionId sessionId,
                               String topics)
                        throws IllegalArgumentException
```
    Subscribe another session to topics.
    This is equivalent to calling subscribe(SessionId, TopicSelector) 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
    
    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;
    PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression ;
    NoSuchSessionException – if there is no session with the given sessionId;
    SessionClosedException – if the session is closed.
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    6.0
  - subscribe
```
CompletableFuture<?> subscribe(SessionId sessionId,
                               TopicSelector topics)
```
    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
    
    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;
    PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression ;
    NoSuchSessionException – if there is no session with the given sessionId;
    SessionClosedException – if the session is closed.
    Since:
    
    6.0
  - subscribe
```
@Deprecated
void subscribe(SessionId sessionId,
                           String topics,
                           SubscriptionControl.SubscriptionCallback 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.
    
    Subscribe another session to topics.
    This is equivalent to calling subscribe(SessionId, TopicSelector, SubscriptionCallback) 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
    
    callback - provides callback methods to indicate success or failure
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
  - subscribe
```
@Deprecated
void subscribe(SessionId sessionId,
                           TopicSelector topics,
                           SubscriptionControl.SubscriptionCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    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
    
    callback - provides callback methods to indicate success or failure
  - subscribe
```
@Deprecated
<C> void subscribe(SessionId sessionId,
                               String topics,
                               C context,
                               SubscriptionControl.SubscriptionContextCallback<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.
    
    Subscribe another session to topics.
    This is equivalent to calling subscribe(SessionId, TopicSelector, Object, SubscriptionContextCallback) with a selector parsed using TopicSelectors.parse(String).
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    sessionId - identifies the session to subscribe
    
    topics - the topics to subscribe to specified as a TopicSelector expression
    
    context - 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 - provides callback methods to indicate success or failure
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
  - subscribe
```
@Deprecated
<C> void subscribe(SessionId sessionId,
                               TopicSelector topics,
                               C context,
                               SubscriptionControl.SubscriptionContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    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.
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    sessionId - identifies the session to subscribe
    
    topics - identifies the topics to subscribe to
    
    context - 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 - provides callback methods to indicate success or failure
  - unsubscribe
```
CompletableFuture<?> unsubscribe(SessionId sessionId,
                                 String topics)
                          throws IllegalArgumentException
```
    Unsubscribe another session from topics.
    This is equivalent to calling unsubscribe(SessionId, TopicSelector) 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
    
    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;
    NoSuchSessionException – if there is no session with the given sessionId;
    SessionClosedException – if the session is closed.
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    6.0
  - unsubscribe
```
CompletableFuture<?> unsubscribe(SessionId sessionId,
                                 TopicSelector topics)
```
    Unsubscribe another session from topics.
    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;
    NoSuchSessionException – if there is no session with the given sessionId;
    SessionClosedException – if the session is closed.
    Since:
    
    6.0
  - unsubscribe
```
@Deprecated
void unsubscribe(SessionId sessionId,
                             String topics,
                             SubscriptionControl.SubscriptionCallback 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.
    
    Unsubscribe another session from topics.
    This is equivalent to calling unsubscribe(SessionId, TopicSelector, SubscriptionCallback) 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
    
    callback - provides callback methods indicating the status of this operation
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
  - unsubscribe
```
@Deprecated
void unsubscribe(SessionId sessionId,
                             TopicSelector topics,
                             SubscriptionControl.SubscriptionCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Unsubscribe another session from topics.
    
    Parameters:
    
    sessionId - identifies the session to unsubscribe
    
    topics - the topics to unsubscribe from
    
    callback - provides callback methods indicating the status of this operation
  - unsubscribe
```
@Deprecated
<C> void unsubscribe(SessionId sessionId,
                                 String topics,
                                 C context,
                                 SubscriptionControl.SubscriptionContextCallback<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.
    
    Unsubscribe another session from topics.
    This is equivalent to calling unsubscribe(SessionId, TopicSelector, Object, SubscriptionContextCallback) with a selector parsed using TopicSelectors.parse(String).
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    sessionId - identifies the session to unsubscribe
    
    topics - the topics to unsubscribe specified as a TopicSelector expression
    
    context - 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 - provides callback methods indicating the status of this operation
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
  - unsubscribe
```
@Deprecated
<C> void unsubscribe(SessionId sessionId,
                                 TopicSelector topics,
                                 C context,
                                 SubscriptionControl.SubscriptionContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Unsubscribe another session from topics.
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    sessionId - identifies the session to unsubscribe
    
    topics - the topics to unsubscribe from
    
    context - 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 - provides callback methods indicating the status of this operation
  - subscribeByFilter
```
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
                                                                                    String topics)
                                                                             throws IllegalArgumentException
```
    Subscribe sessions that satisfy a given session filter to topics.
    This is equivalent to calling subscribeByFilter(String, TopicSelector) 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
    
    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 and VIEW_SESSION global permissions;
    PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression;
    SessionClosedException – if the session is closed.
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    6.0
  - subscribeByFilter
```
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> subscribeByFilter(String filter,
                                                                                    TopicSelector topics)
```
    Subscribe sessions that satisfy a given session filter to topics.
    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
    
    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 and VIEW_SESSION permissions;
    PermissionsException – if the calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression;
    SessionClosedException – if the session is closed.
    Since:
    
    6.0
  - subscribeByFilter
```
@Deprecated
void subscribeByFilter(String filter,
                                   String topics,
                                   SubscriptionControl.SubscriptionByFilterCallback 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.
    
    Subscribe sessions that satisfy a given session filter to topics.
    This is equivalent to calling subscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback) 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
    
    callback - provides callback methods to indicate success or failure
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    5.6
  - subscribeByFilter
```
@Deprecated
void subscribeByFilter(String filter,
                                   TopicSelector topics,
                                   SubscriptionControl.SubscriptionByFilterCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Subscribe sessions that satisfy a given session filter to topics.
    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 - identifies the topics to subscribe to
    
    callback - provides callback methods to indicate success or failure
    
    Since:
    
    5.6
  - subscribeByFilter
```
@Deprecated
<C> void subscribeByFilter(String filter,
                                       String topics,
                                       C context,
                                       SubscriptionControl.SubscriptionByFilterContextCallback<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.
    
    Subscribe sessions that satisfy a given session filter to topics.
    This is equivalent to calling subscribeByFilter(String, TopicSelector, Object, SubscriptionByFilterContextCallback) with a selector parsed using TopicSelectors.parse(String).
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    filter - the session filter expression
    
    topics - the topics to subscribe to specified as a TopicSelector expression
    
    context - 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 - provides callback methods to indicate success or failure
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    5.6
  - subscribeByFilter
```
@Deprecated
<C> void subscribeByFilter(String filter,
                                       TopicSelector topics,
                                       C context,
                                       SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Subscribe sessions that satisfy a given session filter to topics.
    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.
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    filter - the session filter expression
    
    topics - identifies the topics to subscribe to
    
    context - 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 - provides callback methods to indicate success or failure
    
    Since:
    
    5.6
  - unsubscribeByFilter
```
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
                                                                                      String topics)
                                                                               throws IllegalArgumentException
```
    Unsubscribe sessions that satisfy a given session filter from topics.
    This is equivalent to calling unsubscribeByFilter(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 and VIEW_SESSION permissions;
    SessionClosedException – if the session is closed.
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    6.0
  - unsubscribeByFilter
```
CompletableFuture<SubscriptionControl.SubscriptionByFilterResult> unsubscribeByFilter(String filter,
                                                                                      TopicSelector topics)
```
    Unsubscribe sessions that satisfy a given session filter from topics.
    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 and VIEW_SESSION global permissions;
    SessionClosedException – if the session is closed.
    Since:
    
    6.0
  - unsubscribeByFilter
```
@Deprecated
void unsubscribeByFilter(String filter,
                                     String topics,
                                     SubscriptionControl.SubscriptionByFilterCallback 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.
    
    Unsubscribe sessions that satisfy a given session filter from topics.
    This is equivalent to calling unsubscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback) with a selector parsed using TopicSelectors.parse(String).
    
    Parameters:
    
    filter - the session filter expression
    
    topics - the topics to unsubscribe specified as a TopicSelector expression
    
    callback - provides callback methods indicating the status of this operation
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    5.6
  - unsubscribeByFilter
```
@Deprecated
void unsubscribeByFilter(String filter,
                                     TopicSelector topics,
                                     SubscriptionControl.SubscriptionByFilterCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Unsubscribe sessions that satisfy a given session filter from topics.
    
    Parameters:
    
    filter - the session filter expression
    
    topics - the topics to unsubscribe from
    
    callback - provides callback methods indicating the status of this operation
    
    Since:
    
    5.6
  - unsubscribeByFilter
```
@Deprecated
<C> void unsubscribeByFilter(String filter,
                                         String topics,
                                         C context,
                                         SubscriptionControl.SubscriptionByFilterContextCallback<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.
    
    Unsubscribe sessions that satisfy a given session filter from topics.
    This is equivalent to calling unsubscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback) with a selector parsed using TopicSelectors.parse(String).
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    filter - the session filter expression
    
    topics - the topics to unsubscribe specified as a TopicSelector expression
    
    context - 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 - provides callback methods indicating the status of this operation
    
    Throws:
    
    IllegalArgumentException - if topics is not a valid selector expression
    
    Since:
    
    5.6
  - unsubscribeByFilter
```
@Deprecated
<C> void unsubscribeByFilter(String filter,
                                         TopicSelector topics,
                                         C context,
                                         SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Unsubscribe sessions that satisfy a given session filter from topics.
    
    Type Parameters:
    
    C - context object type
    
    Parameters:
    
    filter - the session filter expression
    
    topics - the topics to unsubscribe from
    
    context - 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 - provides callback methods indicating the status of this operation
    
    Since:
    
    5.6

Interface SubscriptionControl

Access control

Accessing the feature

Nested Class Summary

Method Summary

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

Method Detail

addRoutingSubscriptionHandler

addRoutingSubscriptionHandler

subscribe

subscribe

subscribe

subscribe

subscribe

subscribe

unsubscribe

unsubscribe

unsubscribe

unsubscribe

unsubscribe

unsubscribe

subscribeByFilter

subscribeByFilter

subscribeByFilter

subscribeByFilter

subscribeByFilter

subscribeByFilter

unsubscribeByFilter

unsubscribeByFilter

unsubscribeByFilter

unsubscribeByFilter

unsubscribeByFilter

unsubscribeByFilter