com.pushtechnology.diffusion.client.features.control.topics.SubscriptionControl Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2014, 2024 DiffusionData Ltd., All Rights Reserved.
*
* Use is subject to licence terms.
*
* NOTICE: All information contained herein is, and remains the
* property of DiffusionData. The intellectual and technical
* concepts contained herein are proprietary to DiffusionData and
* may be covered by U.S. and Foreign Patents, patents in process, and
* are protected by trade secret or copyright law.
*******************************************************************************/
package com.pushtechnology.diffusion.client.features.control.topics;
import static org.slf4j.LoggerFactory.getLogger;
import java.util.Collection;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.pushtechnology.diffusion.client.callbacks.Callback;
import com.pushtechnology.diffusion.client.callbacks.ContextCallback;
import com.pushtechnology.diffusion.client.features.InvalidFilterException;
import com.pushtechnology.diffusion.client.features.NoSuchSessionException;
import com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventStream;
import com.pushtechnology.diffusion.client.session.Feature;
import com.pushtechnology.diffusion.client.session.PermissionsException;
import com.pushtechnology.diffusion.client.session.Session;
import com.pushtechnology.diffusion.client.session.SessionClosedException;
import com.pushtechnology.diffusion.client.session.SessionId;
import com.pushtechnology.diffusion.client.topics.TopicSelector;
import com.pushtechnology.diffusion.client.topics.TopicSelectors;
import com.pushtechnology.diffusion.client.types.ErrorReport;
import com.pushtechnology.diffusion.client.types.GlobalPermission;
import com.pushtechnology.diffusion.client.types.PathPermission;
/**
* This feature allows a session to subscribe or unsubscribe other sessions to
* topics.
*
* Requests to subscribe sessions to topics can be submitted at any time even if
* the topics do not exist at the server. {@link TopicSelector 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 {@link SessionId} is
* known.
*
* Subscriptions may also be requested using 'session filters' (see
* {@link 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 {@link SessionEventStream session event listeners} can be
* used and those sessions subscribed as required based upon their session
* properties.
*
*
Access control
To subscribe other sessions to topics, a session must
* have {@link GlobalPermission#MODIFY_SESSION MODIFY_SESSION} permission, and
* {@link PathPermission#SELECT_TOPIC 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
* {@link PathPermission#READ_TOPIC READ_TOPIC} permission.
*
* To unsubscribe other sessions, a session must have
* {@link GlobalPermission#MODIFY_SESSION MODIFY_SESSION} permission.
*
* Operations that identify sessions using a session filter require the
* {@link GlobalPermission#VIEW_SESSION VIEW_SESSION} permission.
*
*
Accessing the feature
This feature may be obtained from a
* {@link Session session} as follows:
*
*
*
* SubscriptionControl subsControl = session.feature(SubscriptionControl.class);
*
*
*
* @author DiffusionData Limited
* @since 5.0
*/
public interface SubscriptionControl extends Feature {
/**
* Subscribe another session to topics.
*
*
* This is equivalent to calling
* {@link #subscribe(SessionId, TopicSelector)} with a selector parsed using
* {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to subscribe
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} permission;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code SELECT_TOPIC} permission for the path prefix
* of the selector expression ;
*
*
- {@link NoSuchSessionException} – if there is no session
* with the given {@code sessionId};
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
* @since 6.0
*/
CompletableFuture subscribe(
SessionId sessionId,
String topics)
throws IllegalArgumentException;
/**
* 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
* {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param sessionId identifies the session to subscribe
*
* @param topics identifies the topics to subscribe to
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} permission;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code SELECT_TOPIC} permission for the path prefix
* of the selector expression ;
*
*
- {@link NoSuchSessionException} – if there is no session
* with the given {@code sessionId};
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
* @since 6.0
*/
CompletableFuture subscribe(
SessionId sessionId,
TopicSelector topics);
/**
* Subscribe another session to topics.
*
*
* This is equivalent to calling
* {@link #subscribe(SessionId, TopicSelector, SubscriptionCallback)} with a
* selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to subscribe
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @param callback provides callback methods to indicate success or failure
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribe(
SessionId sessionId,
String topics,
SubscriptionCallback callback)
throws IllegalArgumentException;
/**
* 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
* {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param sessionId identifies the session to subscribe
*
* @param topics identifies the topics to subscribe to
*
* @param callback provides callback methods to indicate success or failure
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribe(
SessionId sessionId,
TopicSelector topics,
SubscriptionCallback callback);
/**
* Subscribe another session to topics.
*
*
* This is equivalent to calling
* {@link #subscribe(SessionId, TopicSelector, Object, SubscriptionContextCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to subscribe
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @param 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 {@code null}
*
* @param callback provides callback methods to indicate success or failure
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @param context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribe(
SessionId sessionId,
String topics,
C context,
SubscriptionContextCallback callback)
throws IllegalArgumentException;
/**
* 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
* {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param sessionId identifies the session to subscribe
*
* @param topics identifies the topics to subscribe to
*
* @param 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 {@code null}
*
* @param callback provides callback methods to indicate success or failure
*
* @param context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribe(
SessionId sessionId,
TopicSelector topics,
C context,
SubscriptionContextCallback callback);
/**
* Unsubscribe another session from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribe(SessionId, TopicSelector)} with a selector parsed
* using {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe specified as a
* {@link TopicSelector} expression
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} permission;
*
*
- {@link NoSuchSessionException} – if there is no session
* with the given {@code sessionId};
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
* @since 6.0
*/
CompletableFuture unsubscribe(
SessionId sessionId,
String topics)
throws IllegalArgumentException;
/**
* Unsubscribe another session from topics.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe from
*
* @return 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 {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} permission;
*
*
- {@link NoSuchSessionException} – if there is no session
* with the given {@code sessionId};
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
* @since 6.0
*/
CompletableFuture unsubscribe(
SessionId sessionId,
TopicSelector topics);
/**
* Unsubscribe another session from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribe(SessionId, TopicSelector, SubscriptionCallback)} with
* a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe specified as a
* {@link TopicSelector} expression
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribe(
SessionId sessionId,
String topics,
SubscriptionCallback callback)
throws IllegalArgumentException;
/**
* Unsubscribe another session from topics.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe from
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribe(
SessionId sessionId,
TopicSelector topics,
SubscriptionCallback callback);
/**
* Unsubscribe another session from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribe(SessionId, TopicSelector, Object, SubscriptionContextCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe specified as a
* {@link TopicSelector} expression
*
* @param 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 {@code null}
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @param context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribe(
SessionId sessionId,
String topics,
C context,
SubscriptionContextCallback callback)
throws IllegalArgumentException;
/**
* Unsubscribe another session from topics.
*
* @param sessionId identifies the session to unsubscribe
*
* @param topics the topics to unsubscribe from
*
* @param 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 {@code null}
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @param context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribe(
SessionId sessionId,
TopicSelector topics,
C context,
SubscriptionContextCallback callback);
/**
* Callback interface to receive status notifications for subscription and
* unsubscription operations.
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface SubscriptionCallback extends
com.pushtechnology.diffusion.client.features.Callback {
/**
* Called to indicate that the requested operation has been processed by
* the server.
*/
void onComplete();
/**
* Default implementation of {@link SubscriptionCallback}.
*
* This simply logs onComplete calls at 'debug' level. This method may
* be overridden to perform more specific processing.
*/
class Default
extends
com.pushtechnology.diffusion.client.features.Callback.Default
implements SubscriptionCallback {
private static final Logger LOG =
getLogger(SubscriptionCallback.Default.class);
@Override
public void onComplete() {
LOG.debug(
"{} - Subscription/Unsubscription complete",
this);
}
}
}
/**
* Contextual callback interface to receive status notifications for
* subscription and unsubscription operations.
*
*
* Use this alternative to {@link SubscriptionCallback} to associate some
* arbitrary context object with each call.
*
* @param context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface SubscriptionContextCallback extends
com.pushtechnology.diffusion.client.features.ContextCallback {
/**
* Called to indicate that the requested operation has been processed by
* the server.
*
* @param context the context object supplied when making the call. May
* be {@code null}.
*/
void onComplete(C context);
/**
* Default implementation of {@link SubscriptionContextCallback}.
*
* This simply logs onComplete calls at 'debug' level. This method may
* be overridden to perform more specific processing.
*
* @param context object type
*/
class Default
extends
com.pushtechnology.diffusion.client.features.ContextCallback.Default
implements SubscriptionContextCallback {
private static final Logger LOG =
getLogger(SubscriptionContextCallback.Default.class);
@Override
public void onComplete(
C context) {
LOG.debug(
"{} - Subscription/Unsubscription complete, context={}",
this,
context);
}
}
}
/**
* Subscribe sessions that satisfy a given session filter to topics.
*
*
* This is equivalent to calling
* {@link #subscribeByFilter(String, TopicSelector)} with a selector parsed
* using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @return a CompletableFuture that completes when the server has processed
* the subscription request.
*
*
* If the subscription was accepted, the CompletableFuture will
* complete successfully with a {@link SubscriptionByFilterResult}.
*
*
* Otherwise, the CompletableFuture will complete exceptionally with
* a {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link InvalidFilterException} – if the filter is
* invalid;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} and {@code VIEW_SESSION}
* global permissions;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code SELECT_TOPIC} permission for the path prefix
* of the selector expression;
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @since 6.0
*/
CompletableFuture subscribeByFilter(
String filter,
String topics)
throws IllegalArgumentException;
/**
* 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 {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param filter the session filter expression
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @return a CompletableFuture that completes when the server has processed
* the subscription request.
*
*
* If the subscription was accepted, the CompletableFuture will
* complete successfully with a {@link SubscriptionByFilterResult}.
*
*
* Otherwise, the CompletableFuture will complete exceptionally with
* a {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link InvalidFilterException} – if the filter is
* invalid;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} and {@code VIEW_SESSION}
* permissions;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code SELECT_TOPIC} permission for the path prefix
* of the selector expression;
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @since 6.0
*/
CompletableFuture subscribeByFilter(
String filter,
TopicSelector topics);
/**
* Subscribe sessions that satisfy a given session filter to topics.
*
*
* This is equivalent to calling
* {@link #subscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @param callback provides callback methods to indicate success or failure
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribeByFilter(
String filter,
String topics,
SubscriptionByFilterCallback callback)
throws IllegalArgumentException;
/**
* 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 {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param filter the session filter expression
*
* @param topics identifies the topics to subscribe to
*
* @param callback provides callback methods to indicate success or failure
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribeByFilter(
String filter,
TopicSelector topics,
SubscriptionByFilterCallback callback);
/**
* Subscribe sessions that satisfy a given session filter to topics.
*
*
* This is equivalent to calling
* {@link #subscribeByFilter(String, TopicSelector, Object, SubscriptionByFilterContextCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to subscribe to specified as a
* {@link TopicSelector} expression
*
* @param 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 {@code null}
*
* @param callback provides callback methods to indicate success or failure
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @param context object type
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribeByFilter(
String filter,
String topics,
C context,
SubscriptionByFilterContextCallback callback)
throws IllegalArgumentException;
/**
* 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 {@code 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 {@code SELECT_TOPIC} permission for a topic
* cannot subscribe directly, but can be subscribed indirectly using this
* method.
*
* @param filter the session filter expression
*
* @param topics identifies the topics to subscribe to
*
* @param 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 {@code null}
*
* @param callback provides callback methods to indicate success or failure
*
* @param context object type
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void subscribeByFilter(
String filter,
TopicSelector topics,
C context,
SubscriptionByFilterContextCallback callback);
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribeByFilter(String, TopicSelector)} with a selector
* parsed using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe from specified as a
* {@link TopicSelector} expression
*
* @return a CompletableFuture that completes when the server has processed
* the unsubscription request.
*
*
* If the unsubscription was accepted, the CompletableFuture will
* complete successfully with a {@link SubscriptionByFilterResult}.
*
*
* Otherwise, the CompletableFuture will complete exceptionally with
* a {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link InvalidFilterException} – if the filter is
* invalid;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} and {@code VIEW_SESSION}
* permissions;
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @since 6.0
*/
CompletableFuture unsubscribeByFilter(
String filter,
String topics)
throws IllegalArgumentException;
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe from specified as a
* {@link TopicSelector} expression
*
* @return a CompletableFuture that completes when the server has processed
* the unsubscription request.
*
*
* If the unsubscription was accepted, the CompletableFuture will
* complete successfully with a {@link SubscriptionByFilterResult}.
*
*
* Otherwise, the CompletableFuture will complete exceptionally with
* a {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
* - {@link InvalidFilterException} – if the filter is
* invalid;
*
*
- {@link PermissionsException} – if the calling session
* does not have {@code MODIFY_SESSION} and {@code VIEW_SESSION}
* global permissions;
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
*
* @since 6.0
*/
CompletableFuture unsubscribeByFilter(
String filter,
TopicSelector topics);
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe specified as a
* {@link TopicSelector} expression
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribeByFilter(
String filter,
String topics,
SubscriptionByFilterCallback callback)
throws IllegalArgumentException;
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe from
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribeByFilter(
String filter,
TopicSelector topics,
SubscriptionByFilterCallback callback);
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
*
* This is equivalent to calling
* {@link #unsubscribeByFilter(String, TopicSelector, SubscriptionByFilterCallback)}
* with a selector parsed using {@link TopicSelectors#parse(String)}.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe specified as a
* {@link TopicSelector} expression
*
* @param 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 {@code null}
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @throws IllegalArgumentException if {@code topics} is not a valid
* selector expression
*
* @param context object type
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribeByFilter(
String filter,
String topics,
C context,
SubscriptionByFilterContextCallback callback)
throws IllegalArgumentException;
/**
* Unsubscribe sessions that satisfy a given session filter from topics.
*
* @param filter the session filter expression
*
* @param topics the topics to unsubscribe from
*
* @param 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 {@code null}
*
* @param callback provides callback methods indicating the status of this
* operation
*
* @param context object type
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void unsubscribeByFilter(
String filter,
TopicSelector topics,
C context,
SubscriptionByFilterContextCallback callback);
/**
* Callback interface for filtered subscriptions and unsubscriptions.
*
* @since 5.6
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface SubscriptionByFilterCallback extends Callback {
/**
* Called to indicate successful processing of the request at the
* server.
*
* @param numberSelected the number of sessions that satisfied the
* filter and qualified for subscription/unsubscription. This
* will be 0 if no sessions satisfied the filter.
*/
void onComplete(int numberSelected);
/**
* The filter was rejected. No sessions were subscribed/unsubscribed.
*
* @param errors the detail of why the filter was rejected
*/
void onRejected(Collection errors);
/**
* Default implementation of {@link SubscriptionByFilterCallback}.
*
* This logs onComplete calls at 'debug' level and onRejected calls at
* 'error' level. This method may be overridden to perform more specific
* processing.
*/
class Default extends
Callback.Default
implements SubscriptionByFilterCallback {
private static final Logger LOG =
LoggerFactory
.getLogger(SubscriptionByFilterCallback.Default.class);
@Override
public void onComplete(int numberSelected) {
LOG.debug(
"{} - Subscription/Unsubscription complete : {} sessions selected",
this,
numberSelected);
}
@Override
public void onRejected(Collection errors) {
LOG.error(
"{} - Subscription/Unsubscription rejected : {}",
this,
errors);
}
}
}
/**
* Callback interface for filtered subscriptions and unsubscriptions that
* have an associated context.
*
* @since 5.6
* @param the context object type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface SubscriptionByFilterContextCallback
extends ContextCallback {
/**
* Called to indicate successful processing of the request at the
* server.
*
* @param context the context object the application supplied when
* making the call; may be {@code null}
*
* @param numberSelected the number of sessions that satisfied the
* filter and qualified for subscription/unsubscription. This
* will be 0 if no sessions satisfied the filter.
*/
void onComplete(C context, int numberSelected);
/**
* The filter was rejected. No sessions were subscribed/unsubscribed.
*
* @param context the context object supplied when making the call
*
* @param errors the detail of why the filter was rejected
*/
void onRejected(C context, Collection errors);
/**
* Default implementation of {@link SubscriptionByFilterContextCallback}
* .
*
* This logs onComplete calls at 'debug' level and onRejected calls at
* 'error' level. This method may be overridden to perform more specific
* processing.
*
* @param context object type
*/
class Default
extends
ContextCallback.Default
implements SubscriptionByFilterContextCallback {
private static final Logger LOG =
getLogger(SubscriptionByFilterContextCallback.Default.class);
@Override
public void onComplete(C context, int numberSelected) {
LOG.debug(
"{} - Subscription/Unsubscription complete : {} sessions selected, Context={}",
this,
numberSelected,
context);
}
@Override
public void onRejected(C context, Collection errors) {
LOG.error(
"{} - Subscription/Unsubscription rejected : {}, Context={}",
this,
errors,
context);
}
}
}
/**
* Result used by CompletableFuture variants of
* {@link SubscriptionControl#subscribeByFilter(String, String)
* subscribeByFilter} and
* {@link SubscriptionControl#unsubscribeByFilter(String, String)
* unsubscribeByFilter}.
*
* @since 6.0
*/
interface SubscriptionByFilterResult {
/**
* @return number of sessions that satisfied the filter and qualified
* for subscription/unsubscription. This will be 0 if no
* sessions satisfied the filter.
*/
int numberSelected();
}
}