Interface ISubscriptionControl

This feature allows a ISession to subscribe or unsubscribe other sessions to topics.

Inherited Members

Namespace: PushTechnology.ClientInterface.Client.Features.Control.Topics

Assembly: Diffusion.Client.dll

Syntax

public interface ISubscriptionControl : IFeature

Remarks

It also provides a mechanism for handling requests to subscribe to routing topics.

Requests to subscribe sessions to topics can be submitted at any time even if the topics do not exist at the server. ITopicSelector 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 ISessionId is known.

Subscriptions may also be requested using 'session filters' (see ISession 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 ISessionPropertiesListener 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(String, IRoutingSubscriptionRequestHandler). 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 AddRoutingSubscriptionHandler(String, IRoutingSubscriptionRequestHandler) the session needs VIEW_SESSION, MODIFY_SESSION and REGISTER_HANDLER permissions.

When handling a subscription request to a routing topic through a routing handler the target session needs to have READ_TOPIC permission to both the routing topic being subscribed to and the target topic that is assigned.

Operations that use a session filter to identify sessions require the permission.

Accessing the feature

This feature is obtained from a ISession as follows:

var subscriptionControl = session.SubscriptionControl;

Methods

AddRoutingSubscriptionHandler(String, IRoutingSubscriptionRequestHandler)

Adds a handler for ROUTING topics that belong to a branch of the topic tree.

Declaration

void AddRoutingSubscriptionHandler(string topicPath, IRoutingSubscriptionRequestHandler handler)

Parameters

Type	Name	Description
String	topicPath	Identifies the branch of the tipic tree to associate the handler with.
IRoutingSubscriptionRequestHandler	handler	The handler to use for routing topics at or bellow the specified path (unless there is a handler registered for a more specific topic path).

Remarks

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.

Subscribe(ISessionId, ITopicSelector, ISubscriptionCallback)

Subscribe another session to topics.

Declaration

void Subscribe(ISessionId session, ITopicSelector topics, ISubscriptionCallback callback)

Parameters

Type	Name	Description
ISessionId	session	The session to subscribe.
ITopicSelector	topics	The topics to subscribe to, specified as a ITopicSelector expression.
ISubscriptionCallback	callback	Provides callback methods to indicate success or failure.

Remarks

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.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Subscribe(ISessionId, String, ISubscriptionCallback)

Subscribe another session to topics.

Declaration

void Subscribe(ISessionId session, string topics, ISubscriptionCallback callback)

Parameters

Type	Name	Description
ISessionId	session	The session to subscribe.
String	topics	The topics to subscribe to.
ISubscriptionCallback	callback	Provides callback methods to indicate success or failure.

Remarks

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

Subscribe<TC>(ISessionId, ITopicSelector, TC, ISubscriptionContextCallback<TC>)

Subscribe another session to topics.

Declaration

void Subscribe<TC>(ISessionId session, ITopicSelector topics, TC context, ISubscriptionContextCallback<TC> callback)

Parameters

Type	Name	Description
ISessionId	session	The session to subscribe.
ITopicSelector	topics	The topics to subscribe to, specified as a ITopicSelector expression.
TC	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`.
ISubscriptionContextCallback<TC>	callback	Provides callback methods to indicate success or failure.

Type Parameters

Name	Description
TC	The context object type.

Remarks

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

Caution

Subscribe<TC>(ISessionId, String, TC, ISubscriptionContextCallback<TC>)

Subscribe another session to topics.

Declaration

void Subscribe<TC>(ISessionId session, string topics, TC context, ISubscriptionContextCallback<TC> callback)

Parameters

Type	Name	Description
ISessionId	session	The session to subscribe.
String	topics	The topics to subscribe to.
TC	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`.
ISubscriptionContextCallback<TC>	callback	Provides callback methods to indicate success or failure.

Type Parameters

Name	Description
TC	The context object type.

Remarks

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

SubscribeAsync(ISessionId, String)

Subscribe another session to topics.

Declaration

Task<object> SubscribeAsync(ISessionId sessionId, string topics)

Parameters

Type	Name	Description
ISessionId	sessionId	The session to subscribe.
String	topics	The topics to subscribe to.

Returns

Type	Description
Task<Object>	The `Task` representing the current operation.

Remarks

Added in version 6.6.

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

Exceptions

Type	Condition
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SubscribeAsync(ISessionId, String, CancellationToken)

Subscribe another session to topics.

Declaration

Task<object> SubscribeAsync(ISessionId sessionId, string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	The session to subscribe.
String	topics	The topics to subscribe to.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<Object>	The `Task` representing the current operation.

Remarks

Added in version 6.6.

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

Exceptions

Type	Condition
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SubscribeByFilter(String, ITopicSelector, ISubscriptionByFilterCallback)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

void SubscribeByFilter(string filter, ITopicSelector topics, ISubscriptionByFilterCallback callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
ITopicSelector	topics	The topics to subscribe to specified as a ITopicSelector expression.
ISubscriptionByFilterCallback	callback	Provides callback methods to indicate success or failure.

Remarks

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.

Caution

SubscribeByFilter(String, String, ISubscriptionByFilterCallback)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

void SubscribeByFilter(string filter, string topics, ISubscriptionByFilterCallback callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to subscribe to.
ISubscriptionByFilterCallback	callback	Provides callback methods to indicate success or failure.

Remarks

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

SubscribeByFilter<TC>(String, ITopicSelector, TC, ISubscriptionByFilterContextCallback<TC>)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

void SubscribeByFilter<TC>(string filter, ITopicSelector topics, TC context, ISubscriptionByFilterContextCallback<TC> callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
ITopicSelector	topics	The topics to subscribe to, specified as a ITopicSelector expression.
TC	context	Parsed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including `null`.
ISubscriptionByFilterContextCallback<TC>	callback

Type Parameters

Name	Description
TC	The context object type.

Remarks

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

Caution

SubscribeByFilter<TC>(String, String, TC, ISubscriptionByFilterContextCallback<TC>)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

void SubscribeByFilter<TC>(string filter, string topics, TC context, ISubscriptionByFilterContextCallback<TC> callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to subscribe to, specified as a ITopicSelector expression.
TC	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`.
ISubscriptionByFilterContextCallback<TC>	callback	Provides callback methods to indicate success or failure.

Type Parameters

Name	Description
TC	The context object type.

Remarks

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

SubscribeByFilterAsync(String, String)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

Task<ISubscriptionByFilterResult> SubscribeByFilterAsync(string filter, string topics)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to subscribe to.

Returns

Type	Description
Task<ISubscriptionByFilterResult>	The `Task` representing the current operation.

Remarks

This is equivalent to calling with a selector parsed using Parse(String).

Exceptions

Type	Condition
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION global permissions. Thrown by the returned task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SubscribeByFilterAsync(String, String, CancellationToken)

Subscribe all sessions that satisfy a given session filter to topics.

Declaration

Task<ISubscriptionByFilterResult> SubscribeByFilterAsync(string filter, string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to subscribe to.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<ISubscriptionByFilterResult>	The `Task` representing the current operation.

Remarks

This is equivalent to calling with a selector parsed using Parse(String).

Exceptions

Type	Condition
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION global permissions. Thrown by the returned task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permission for the path prefix of the selector expression. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

Unsubscribe(ISessionId, ITopicSelector, ISubscriptionCallback)

Unsubscribe another session from topics.

Declaration

void Unsubscribe(ISessionId session, ITopicSelector topics, ISubscriptionCallback callback)

Parameters

Type	Name	Description
ISessionId	session	The session to unsubscribe.
ITopicSelector	topics	The topics to unsubscribe from, specified as a ITopicSelector expression.
ISubscriptionCallback	callback	Provides callback methods indicating the status of this operation.

Remarks

Caution

Unsubscribe(ISessionId, String, ISubscriptionCallback)

Unsubscribe another session from topics.

Declaration

void Unsubscribe(ISessionId session, string topics, ISubscriptionCallback callback)

Parameters

Type	Name	Description
ISessionId	session	The session to unsubscribe.
String	topics	The topics to unsubscribe from.
ISubscriptionCallback	callback	Provides callback methods indicating the status of this operation.

Unsubscribe<TC>(ISessionId, ITopicSelector, TC, ISubscriptionContextCallback<TC>)

Unsubscribe another session from topics.

Declaration

void Unsubscribe<TC>(ISessionId session, ITopicSelector topics, TC context, ISubscriptionContextCallback<TC> callback)

Parameters

Type	Name	Description
ISessionId	session	Identifies the session to unsubscribe.
ITopicSelector	topics	The topics to unsubscribe from, specified as a ITopicSelector expression.
TC	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`.
ISubscriptionContextCallback<TC>	callback	Provides callback methods indicating the status of this operation.

Type Parameters

Name	Description
TC	The context object type.

Remarks

Caution

Unsubscribe<TC>(ISessionId, String, TC, ISubscriptionContextCallback<TC>)

Unsubscribe another session from topics.

Declaration

void Unsubscribe<TC>(ISessionId session, string topics, TC context, ISubscriptionContextCallback<TC> callback)

Parameters

Type	Name	Description
ISessionId	session	The session to unsubscribe.
String	topics	The topics to unsubscribe from.
TC	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`.
ISubscriptionContextCallback<TC>	callback	Provides callback methods indicating the status of this operation.

Type Parameters

Name	Description
TC	The context object type.

UnsubscribeAsync(ISessionId, String)

Unsubscribe another session from topics.

Declaration

Task<object> UnsubscribeAsync(ISessionId sessionId, string topics)

Parameters

Type	Name	Description
ISessionId	sessionId	The session to unsubscribe.
String	topics	The topics to unsubscribe from.

Returns

Type	Description
Task<Object>	The `Task` representing the current operation.

Remarks

Added in version 6.6.

Exceptions

Type	Condition
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

UnsubscribeAsync(ISessionId, String, CancellationToken)

Unsubscribe another session from topics.

Declaration

Task<object> UnsubscribeAsync(ISessionId sessionId, string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	The session to unsubscribe.
String	topics	The topics to unsubscribe from.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<Object>	The `Task` representing the current operation.

Remarks

Added in version 6.6.

Exceptions

Type	Condition
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

UnsubscribeByFilter(String, ITopicSelector, ISubscriptionByFilterCallback)

Unsubscribe all sessions that satisfy a given session filter from topics.

Declaration

void UnsubscribeByFilter(string filter, ITopicSelector topics, ISubscriptionByFilterCallback callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
ITopicSelector	topics	The topics to unsubscribe from, specified as a ITopicSelector expression.
ISubscriptionByFilterCallback	callback	Provides callback methods indicating the status of this operation.

Remarks

Caution

UnsubscribeByFilter(String, String, ISubscriptionByFilterCallback)

Unsubscribe all sessions that satisfy a given session filter from topics.

Declaration

void UnsubscribeByFilter(string filter, string topics, ISubscriptionByFilterCallback callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to unsubscribe from.
ISubscriptionByFilterCallback	callback	Provides callback methods indicating the status of this operation.

UnsubscribeByFilter<TC>(String, ITopicSelector, TC, ISubscriptionByFilterContextCallback<TC>)

Unsubscribe all sessions that satisfy a given session filter from topics.

Declaration

void UnsubscribeByFilter<TC>(string filter, ITopicSelector topics, TC context, ISubscriptionByFilterContextCallback<TC> callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
ITopicSelector	topics	The topics to unsubscribe from, pecified as a ITopicSelector expression.
TC	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`.
ISubscriptionByFilterContextCallback<TC>	callback	Provides callback methods indicating the status of this operation.

Type Parameters

Name	Description
TC	The context object type.

Remarks

Caution

UnsubscribeByFilter<TC>(String, String, TC, ISubscriptionByFilterContextCallback<TC>)

Unsubscribe all sessions that satisfy a given session filter from topics.

Declaration

void UnsubscribeByFilter<TC>(string filter, string topics, TC context, ISubscriptionByFilterContextCallback<TC> callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to unsubscribe specified as a ITopicSelector expression.
TC	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`.
ISubscriptionByFilterContextCallback<TC>	callback	Provides callback methods indicating the status of this operation.

Type Parameters

Name	Description
TC	The context object type.

UnsubscribeByFilterAsync(String, String)

Unsubscribe all sessions that satisfy a given session filter to topics.

Declaration

Task<ISubscriptionByFilterResult> UnsubscribeByFilterAsync(string filter, string topics)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to unsubscribe from.

Returns

Type	Description
Task<ISubscriptionByFilterResult>	The `Task` representing the current operation.

Remarks

This is equivalent to calling with a selector parsed using Parse(String).

Exceptions

Type	Condition
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION global permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

UnsubscribeByFilterAsync(String, String, CancellationToken)

Unsubscribe all sessions that satisfy a given session filter to topics.

Declaration

Task<ISubscriptionByFilterResult> UnsubscribeByFilterAsync(string filter, string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	topics	The topics to unsubscribe from.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<ISubscriptionByFilterResult>	The `Task` representing the current operation.

Remarks

This is equivalent to calling with a selector parsed using Parse(String).

Exceptions

Type	Condition
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION global permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.