public interface SubscriptionControl extends Feature
Requests to subscribe clients 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 client
will become subscribed to any topics that exist at the server that match the
selector (unless they are already subscribed, or the client has insufficient
permission). The subscription request is also retained at the server so that
if any newly created topics match the selector, the client will then become
subscribed to it (unless a subsequent unsubscription cancels it).
Specific client sessions may be subscribed/unsubscribed if the
SessionId
is known.
Subscriptions may also be requested using '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 details listeners
can be used and
those sessions subscribed as required based upon their session properties.
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 target client needs READ_TOPIC
permission to both the routing topic being subscribed to and the target topic
that is assigned.
session
as follows:
SubscriptionControl subsControl = session.feature(SubscriptionControl.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
SubscriptionControl.RoutingSubscriptionRequest
Encapsulates a request to subscribe to Routing Topic and a mechanism for
performing the subscription.
|
static interface |
SubscriptionControl.SubscriptionByFilterCallback
Callback interface for filtered subscriptions and unsubscriptions.
|
static interface |
SubscriptionControl.SubscriptionByFilterContextCallback<C>
Callback interface for filtered subscriptions and unsubscriptions that
have an associated context.
|
static interface |
SubscriptionControl.SubscriptionCallback
Callback interface to receive status notifications for subscription and
unsubscription operations.
|
static interface |
SubscriptionControl.SubscriptionContextCallback<C>
Contextual callback interface to receive status notifications for
subscription and unsubscription operations.
|
Modifier and Type | Method and Description |
---|---|
void |
addRoutingSubscriptionHandler(String topicPath,
SubscriptionControl.RoutingSubscriptionRequest.Handler handler)
Adds a handler to associate with a particular node in the topic tree that
will be called upon requests by other client sessions to subscribe to
routing topics where there is no routing
subscription handler declared at the server. |
<C> void |
subscribe(SessionId sessionId,
String topics,
C context,
SubscriptionControl.SubscriptionContextCallback<C> callback)
Subscribe a client session to topics.
|
void |
subscribe(SessionId sessionId,
String topics,
SubscriptionControl.SubscriptionCallback callback)
Subscribe a client session to topics.
|
<C> void |
subscribe(SessionId sessionId,
TopicSelector topics,
C context,
SubscriptionControl.SubscriptionContextCallback<C> callback)
Subscribe a client session to topics.
|
void |
subscribe(SessionId sessionId,
TopicSelector topics,
SubscriptionControl.SubscriptionCallback callback)
Subscribe a client session to topics.
|
<C> void |
subscribeByFilter(String filter,
String topics,
C context,
SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
Subscribe to all sessions that satisfy a given session filter to topics.
|
void |
subscribeByFilter(String filter,
String topics,
SubscriptionControl.SubscriptionByFilterCallback callback)
Subscribe to all sessions that satisfy a given session filter to topics.
|
<C> void |
subscribeByFilter(String filter,
TopicSelector topics,
C context,
SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
Subscribe to all sessions that satisfy a given session filter to topics.
|
void |
subscribeByFilter(String filter,
TopicSelector topics,
SubscriptionControl.SubscriptionByFilterCallback callback)
Subscribe to all sessions that satisfy a given session filter to topics.
|
<C> void |
unsubscribe(SessionId sessionId,
String topics,
C context,
SubscriptionControl.SubscriptionContextCallback<C> callback)
Unsubscribe a client session from topics.
|
void |
unsubscribe(SessionId sessionId,
String topics,
SubscriptionControl.SubscriptionCallback callback)
Unsubscribe a client session from topics.
|
<C> void |
unsubscribe(SessionId sessionId,
TopicSelector topics,
C context,
SubscriptionControl.SubscriptionContextCallback<C> callback)
Unsubscribe a client session from topics.
|
void |
unsubscribe(SessionId sessionId,
TopicSelector topics,
SubscriptionControl.SubscriptionCallback callback)
Unsubscribe a client session from topics.
|
<C> void |
unsubscribeByFilter(String filter,
String topics,
C context,
SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
Unsubscribe all sessions that satisfy a given session filter from topics.
|
void |
unsubscribeByFilter(String filter,
String topics,
SubscriptionControl.SubscriptionByFilterCallback callback)
Unsubscribe all sessions that satisfy a given session filter from topics.
|
<C> void |
unsubscribeByFilter(String filter,
TopicSelector topics,
C context,
SubscriptionControl.SubscriptionByFilterContextCallback<C> callback)
Unsubscribe all sessions that satisfy a given session filter from topics.
|
void |
unsubscribeByFilter(String filter,
TopicSelector topics,
SubscriptionControl.SubscriptionByFilterCallback callback)
Unsubscribe all sessions that satisfy a given session filter from topics.
|
getSession
void addRoutingSubscriptionHandler(String topicPath, SubscriptionControl.RoutingSubscriptionRequest.Handler handler) throws IllegalArgumentException, SessionClosedException
routing
topics where there is no routing
subscription handler declared at the server.topicPath
- identifies a topic node to associate the handler withhandler
- specifies the handler for the specified node and all
subordinate nodes (unless overridden by another handler)IllegalArgumentException
- if either topicPath
or
handler
is nullSessionClosedException
- if session is closedvoid subscribe(SessionId sessionId, String topics, SubscriptionControl.SubscriptionCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client to subscribetopics
- the topics to subscribe to specified as a
TopicSelector
expressioncallback
- provides callback methods to indicate success or failureIllegalArgumentException
- if any parameter is null or the
topics
expression is invalidSessionClosedException
- if the local session is closedvoid subscribe(SessionId sessionId, TopicSelector topics, SubscriptionControl.SubscriptionCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client to subscribetopics
- identifies the topics to subscribe tocallback
- provides callback methods to indicate success or failureIllegalArgumentException
- if any of the parameters is nullSessionClosedException
- if the local session is closed<C> void subscribe(SessionId sessionId, String topics, C context, SubscriptionControl.SubscriptionContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typesessionId
- identifies the client session to subscribetopics
- the topics to subscribe to specified as a
TopicSelector
expressioncontext
- 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 failureIllegalArgumentException
- if sessionId
, topics
or
callback
is null or topics
is not a valid
selector expressionSessionClosedException
- if the local session is closed<C> void subscribe(SessionId sessionId, TopicSelector topics, C context, SubscriptionControl.SubscriptionContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typesessionId
- identifies the client session to subscribetopics
- identifies the topics to subscribe tocontext
- 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 failureIllegalArgumentException
- if sessionId
, topics
or
callback
is nullSessionClosedException
- if the local session is closedvoid unsubscribe(SessionId sessionId, String topics, SubscriptionControl.SubscriptionCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client session to unsubscribetopics
- the topics to unsubscribe specified as a
TopicSelector
expressioncallback
- provides callback methods indicating the status of this
operation.IllegalArgumentException
- if any parameter is null or
topics
does not specify a valid TopicSelector
expressionSessionClosedException
- if the local session is closedvoid unsubscribe(SessionId sessionId, TopicSelector topics, SubscriptionControl.SubscriptionCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client session to unsubscribetopics
- the topics to unsubscribe fromcallback
- provides callback methods indicating the status of this
operation.IllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closed<C> void unsubscribe(SessionId sessionId, String topics, C context, SubscriptionControl.SubscriptionContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typesessionId
- identifies the client session to unsubscribetopics
- the topics to unsubscribe specified as a
TopicSelector
expressioncontext
- 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.IllegalArgumentException
- if sessionId
, topics
or
callback
is null or topics
does not specify a
valid TopicSelector
expressionSessionClosedException
- if the local session is closed<C> void unsubscribe(SessionId sessionId, TopicSelector topics, C context, SubscriptionControl.SubscriptionContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typesessionId
- identifies the client session to unsubscribetopics
- the topics to unsubscribe fromcontext
- 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.IllegalArgumentException
- if sessionId
, topics
or
callback
is nullSessionClosedException
- if the local session is closedvoid subscribeByFilter(String filter, String topics, SubscriptionControl.SubscriptionByFilterCallback callback) throws IllegalArgumentException, SessionClosedException
filter
- the session filter expressiontopics
- the topics to subscribe to specified as a
TopicSelector
expressioncallback
- provides callback methods to indicate success or failureIllegalArgumentException
- if any parameter is null or the
topics
expression is invalidSessionClosedException
- if the local session is closedvoid subscribeByFilter(String filter, TopicSelector topics, SubscriptionControl.SubscriptionByFilterCallback callback) throws IllegalArgumentException, SessionClosedException
filter
- the session filter expressiontopics
- identifies the topics to subscribe tocallback
- provides callback methods to indicate success or failureIllegalArgumentException
- if any of the parameters is nullSessionClosedException
- if the local session is closed<C> void subscribeByFilter(String filter, String topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typefilter
- the session filter expressiontopics
- the topics to subscribe to specified as a
TopicSelector
expressioncontext
- 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 failureIllegalArgumentException
- if sessionId
, topics
or
callback
is null or topics
is not a valid
selector expressionSessionClosedException
- if the local session is closed<C> void subscribeByFilter(String filter, TopicSelector topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typefilter
- the session filter expressiontopics
- identifies the topics to subscribe tocontext
- 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 failureIllegalArgumentException
- if sessionId
, topics
or
callback
is nullSessionClosedException
- if the local session is closedvoid unsubscribeByFilter(String filter, String topics, SubscriptionControl.SubscriptionByFilterCallback callback) throws IllegalArgumentException, SessionClosedException
filter
- the session filter expressiontopics
- the topics to unsubscribe specified as a
TopicSelector
expressioncallback
- provides callback methods indicating the status of this
operation.IllegalArgumentException
- if any parameter is null or
topics
does not specify a valid TopicSelector
expressionSessionClosedException
- if the local session is closedvoid unsubscribeByFilter(String filter, TopicSelector topics, SubscriptionControl.SubscriptionByFilterCallback callback) throws IllegalArgumentException, SessionClosedException
filter
- the session filter expressiontopics
- the topics to unsubscribe fromcallback
- provides callback methods indicating the status of this
operation.IllegalArgumentException
- if any parameter is nullSessionClosedException
- if the local session is closed<C> void unsubscribeByFilter(String filter, String topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typefilter
- the session filter expressiontopics
- the topics to unsubscribe specified as a
TopicSelector
expressioncontext
- 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.IllegalArgumentException
- if sessionId
, topics
or
callback
is null or topics
does not specify a
valid TopicSelector
expressionSessionClosedException
- if the local session is closed<C> void unsubscribeByFilter(String filter, TopicSelector topics, C context, SubscriptionControl.SubscriptionByFilterContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- context object typefilter
- the session filter expressiontopics
- the topics to unsubscribe fromcontext
- 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.IllegalArgumentException
- if sessionId
, topics
or
callback
is nullSessionClosedException
- if the local session is closedCopyright © 2016 Push Technology Ltd. All Rights Reserved.