com.pushtechnology.diffusion.client.features.control.clients.ClientControl Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2023 DiffusionData Ltd., All Rights Reserved.
*
* Use is subject to license terms.
*
* NOTICE: All information contained herein is, and remains the
* property of Push Technology. The intellectual and technical
* concepts contained herein are proprietary to Push Technology 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.clients;
import static org.slf4j.LoggerFactory.getLogger;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.pushtechnology.diffusion.client.Diffusion;
import com.pushtechnology.diffusion.client.callbacks.Callback;
import com.pushtechnology.diffusion.client.callbacks.ContextCallback;
import com.pushtechnology.diffusion.client.callbacks.Registration;
import com.pushtechnology.diffusion.client.callbacks.ServerHandler;
import com.pushtechnology.diffusion.client.callbacks.Stream;
import com.pushtechnology.diffusion.client.features.HandlerConflictException;
import com.pushtechnology.diffusion.client.features.InvalidFilterException;
import com.pushtechnology.diffusion.client.features.NoSuchSessionException;
import com.pushtechnology.diffusion.client.features.RegisteredHandler;
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.types.GlobalPermission;
/**
* This feature provides the ability for a client session to control other
* client sessions.
*
* It allows for notifications of client sessions starting and closing as well
* as the ability to manage client sessions (forcibly closing them etc).
*
*
Access control
A session must have
* {@link GlobalPermission#VIEW_SESSION VIEW_SESSION} permission to be able to
* listen for notifications using
* {@link #setSessionPropertiesListener(SessionPropertiesListener, String...)}
* or
* {@link #getSessionProperties(SessionId, Collection, SessionPropertiesCallback)
* get properties} of other sessions or listen for
* {@link #setQueueEventHandler(QueueEventHandler) queue events}. In addition
* {@link GlobalPermission#REGISTER_HANDLER REGISTER_HANDLER} permission is
* required to set a session properties listener or queue event handler.
*
* In order to perform operations that change a session's state (such as
* conflating, closing the session, or changing roles), both
* {@link GlobalPermission#VIEW_SESSION VIEW_SESSION} and
* {@link GlobalPermission#MODIFY_SESSION MODIFY_SESSION} permissions are
* required.
*
*
Accessing the feature
This feature may be obtained from a
* {@link Session session} as follows:
*
*
*
* ClientControl clientControl = session.feature(ClientControl.class);
*
*
*
* @author DiffusionData Limited
* @since 5.0
*/
public interface ClientControl extends Feature {
/**
* Register a listener that will be notified when client sessions are
* opened, disconnected, reconnected, closed or when selected session
* property values are updated.
*
* When a listener is first set, it will be called with the required
* properties of all currently open client sessions. The amount of data
* transferred from the server is proportional to the number of connected
* clients and is potentially large. The amount of data can be reduced using
* the {@code requiredProperties} parameter.
*
* Each control session can register a single listener. When the listener is
* no longer required, it may be closed using the {@link Registration}
* provided by the CompletableFuture result. To change the listener, the
* previous listener must first be closed.
*
* The {@code requiredProperties} parameter is used to select the property
* values required.
*
* The requested property set controls the level of detail provided and
* whether the listener is called for updates to sessions. If no properties
* are requested, the listener is not called when session properties are
* updated.
*
* @param listener the listener to be called with session notifications
*
* @param requiredProperties a list of required property keys. See
* {@link Session} for a full list of available fixed property keys.
* To request no properties supply an empty list. To request all
* fixed properties include {@link Session#ALL_FIXED_PROPERTIES} as a
* key. In this case any other fixed property keys would be ignored.
* To request all user properties include
* {@link Session#ALL_USER_PROPERTIES} as a key. In this case any
* other user properties are ignored.
*
* @return a CompletableFuture that completes when the listener has been
* registered, returning a {@link Registration} which can be used to
* unregister the listener.
*
* 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 SessionClosedException} – if the session is
* closed;
*
*
- {@link HandlerConflictException} – if the session has
* already registered a queue event handler;
*
*
- {@link PermissionsException} – if the session does
* not have {@code REGISTER_HANDLER} permission;
*
*
- {@link PermissionsException} – if the session does
* not have {@code VIEW_SESSION} permission.
*
*
* @since 6.0
*/
CompletableFuture setSessionPropertiesListener(
SessionPropertiesStream listener,
String... requiredProperties);
/**
* Register a listener that will be notified when client sessions are
* opened, disconnected, reconnected, closed or when selected session
* property values are updated.
*
* When a listener is first set, it will be called with the required
* properties of all currently open client sessions. The amount of data
* transferred from the server is proportional to the number of connected
* clients and is potentially large. The amount of data can be reduced using
* the {@code requiredProperties} parameter.
*
* Each control session can register a single listener. (See
* {@link SessionPropertiesListener#onRegistered(Registration)}). A listener
* may be closed (using {@link Registration#close()}) if no longer required.
* To set a different listener the current listener must first be closed.
*
* The {@code requiredProperties} parameter is used to select the property
* values required.
*
* The requested property set controls the level of detail provided and
* whether the listener is called for updates to sessions. If no properties
* are requested, the listener is not called when session properties are
* updated.
*
* @param listener the listener to be called with session notifications
*
* @param requiredProperties a list of required property keys. See
* {@link Session} for a full list of available fixed property keys.
* To request no properties supply an empty list. To request all
* fixed properties include {@link Session#ALL_FIXED_PROPERTIES} as a
* key. In this case any other fixed property keys would be ignored.
* To request all user properties include
* {@link Session#ALL_USER_PROPERTIES} as a key. In this case any
* other user properties are ignored.
*
* @since 5.6
*
* @deprecated since 6.7
*
* The CompletableFuture-based alternative
* {@link #setSessionPropertiesListener(SessionPropertiesStream, String...)}
* should be preferred since it provides better error reporting.
*/
@Deprecated
void setSessionPropertiesListener(
SessionPropertiesListener listener,
String... requiredProperties);
/**
* The handler for session properties listener notifications.
*
* This is used along with
* {@link ClientControl#setSessionPropertiesListener(SessionPropertiesListener, String...)}
* to obtain notifications for client sessions.
*
* Callbacks with a {@code properties} parameter provide a map of the
* property values requested when registering the listener.
*
* @since 5.6
*
* @deprecated since 6.7
*
* Use {@link SessionPropertiesStream} instead.
*/
@Deprecated
interface SessionPropertiesListener extends ServerHandler {
/**
* Event type.
*/
enum EventType {
/**
* One or more relevant session properties have been updated.
*/
UPDATED,
/**
* Session has reconnected.
*/
RECONNECTED,
/**
* Use in a clustered configuration to indicate that the session
* failed over from another server.
*/
FAILED_OVER,
/**
* Session has disconnected.
*
* Clients that use an earlier version of the API, released before
* 5.8, will not be notified of session disconnections.
*
* @since 5.8
*/
DISCONNECTED
}
/**
* Notification that a new client session has been opened.
*
* When the listener is registered, this will be called for all existing
* sessions. It will then be called for every new session that opens
* whilst the listener is registered.
*
* This will be called for every client session regardless of requested
* session properties.
*
* @param sessionId the session identifier
*
* @param properties the map of requested session property values. This
* can be empty if no properties were requested. If a requested
* property did not exist, it will not be present in the map.
*/
void onSessionOpen(
SessionId sessionId,
Map properties);
/**
* Notification of a session event that can result in a change of
* properties.
*
* @param sessionId the client session id
*
* @param eventType indicates the type of event
*
* @param properties the map of current requested property values. This
* can be empty if no properties were requested. If a requested
* property did not exist, it will not be present in the map.
*
* @param previousValues a map of the previous values of keys that have
* changed. This will only contain keys that have changed and not
* the whole required property set. This can be empty if an event
* is being reported that did not result in the change of any of
* the required properties. When a new property is added, the
* value in this map will be null. When a property is removed, it
* will have a value in this map but not in {@code properties}.
*/
void onSessionEvent(
SessionId sessionId,
EventType eventType,
Map properties,
Map previousValues);
/**
* Notification that a client session has closed.
*
* This will be called for every client that closes whilst the listener
* is registered regardless of requested session properties.
*
* @param sessionId the session identifier of the client that has closed
*
* @param properties the map of requested property values at the point
* when the session was closed. This can be empty if no
* properties were requested. If a requested property did not
* exist, it will not be present in the map.
*
* @param closeReason why the session was closed
*/
void onSessionClose(
SessionId sessionId,
Map properties,
CloseReason closeReason);
/**
* This provides a default implementation of
* {@link SessionPropertiesListener} which will simply log session
* properties callbacks at debug level. This should only be used for
* diagnostic purposes.
*/
class Default extends ServerHandler.Default
implements SessionPropertiesListener {
private static final Logger LOG =
LoggerFactory
.getLogger(SessionPropertiesListener.Default.class);
@Override
public void onSessionOpen(
SessionId sessionId,
Map properties) {
LOG.debug(
"{} - Client session {} opened : {}",
this,
sessionId,
properties);
}
@Override
public void onSessionEvent(
SessionId sessionId,
EventType eventType,
Map properties,
Map previousValues) {
LOG.debug(
"{} - Client session {} event : {}, Properties={}, Previous Values={}",
this,
sessionId,
eventType,
properties,
previousValues);
}
@Override
public void onSessionClose(
SessionId sessionId,
Map properties,
CloseReason closeReason) {
LOG.debug(
"{} - Client session {} closed - {} : {}",
this,
sessionId,
closeReason,
properties);
}
}
}
/**
* Query the server for property values of a specified client session.
*
* @param sessionId identifies the client session
*
* @param requiredProperties a list of required property keys. See
* {@link Session} for a full list of available fixed property keys.
* To request no properties supply an empty list. To request all
* fixed properties include {@link Session#ALL_FIXED_PROPERTIES} as a
* key. In this case any other fixed property keys would be ignored.
* To request all user properties include
* {@link Session#ALL_USER_PROPERTIES} as a key. In this case any
* other user properties are ignored.
*
* @return a CompletableFuture that completes when a response is received
* from the server, returning a map of the requested session
* property values.
*
*
* If the session properties were retrieved, the CompletableFuture
* will complete successfully. The result type is a map of
* properties that were required. If no properties were selected,
* the map will be empty.
*
* 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 NoSuchSessionException} – if the identified
* session was closed before the response was delivered;
*
*
- {@link PermissionsException} – if the calling
* session does not have the {@code VIEW_SESSION} permission;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.5
*/
CompletableFuture> getSessionProperties(
SessionId sessionId,
Collection requiredProperties);
/**
* Query the server for property values of a specified client session.
*
* @param sessionId identifies the client session
*
* @param requiredProperties a list of required property keys. See
* {@link Session} for a full list of available fixed property keys.
* To request no properties supply an empty list. To request all
* fixed properties include {@link Session#ALL_FIXED_PROPERTIES} as a
* key. In this case any other fixed property keys would be ignored.
* To request all user properties include
* {@link Session#ALL_USER_PROPERTIES} as a key. In this case any
* other user properties are ignored.
*
* @param callback called with the response
*
* @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 getSessionProperties(
SessionId sessionId,
Collection requiredProperties,
SessionPropertiesCallback callback);
/**
* Query the server for property values of a specified client session.
*
* @param sessionId identifies the client session
*
* @param requiredProperties a list of required property keys. See
* {@link Session} for a full list of available fixed property keys.
* To request no properties supply an empty list. To request all
* fixed properties include {@link Session#ALL_FIXED_PROPERTIES} as a
* key. In this case any other fixed property keys would be ignored.
* To request all user properties include
* {@link Session#ALL_USER_PROPERTIES} as a key. In this case any
* other user properties are ignored.
*
* @param context passed to the callback to allow requests and responses to
* be correlated. The caller can use any convenient object reference,
* including {@code null}
*
* @param callback called with the response
*
* @param the 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 getSessionProperties(
SessionId sessionId,
Collection requiredProperties,
C context,
SessionPropertiesContextCallback callback);
/**
* Send a request to the server to change the user-defined session
* properties for a session.
*
* It is also permissible to change the values of the following fixed
* session properties :-
*
* - {@link Session#COUNTRY $Country} - will be normalised to upper case
*
- {@link Session#LANGUAGE $Language} - will be normalised to lower case
*
- {@link Session#LATITUDE $Latitude} - Invalid value will be set to "NaN"
*
- {@link Session#LONGITUDE $Longitude} - Invalid value will be set to "NaN"
*
* If values are provided for any other fixed session properties they will
* be ignored.
*
* @param sessionId identifies the client session
*
* @param properties the properties to change. Each entry in the map is a
* property name and the new value. If the value is {@code null}, any
* existing property with that name will be removed (unless it is a
* fixed property). Otherwise if the property name does not match any
* existing property, that entry will be added as a new property
* (although new properties starting with '$' will be ignored).
*
* @return a CompletableFuture that completes when a response is received
* from the server, returning a map of session properties that
* changed.
*
*
* If the session properties were updated, the CompletableFuture
* will complete successfully. The result type is a map of
* properties that changed with their previous values. If no
* properties were changed, the map will be empty. If any new
* properties were added, the values in the map will be {@code null}
* to indicate that they do not have an old value.
*
* 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 NoSuchSessionException} – if the identified
* session was closed before the response was delivered;
*
*
- {@link PermissionsException} – if the calling
* session does not have {@code MODIFY_SESSION} and
* {@code VIEW_SESSION} permission;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.0
*/
CompletableFuture> setSessionProperties(SessionId sessionId, Map properties);
/**
* Send a request to the server to set all sessions that satisfy a session
* filter with the new user-defined session properties.
*
* It is also permissible to change the values of the following fixed
* session properties:
*
* - {@link Session#COUNTRY $Country} - will be normalised to upper case
*
- {@link Session#LANGUAGE $Language} - will be normalised to lower case
*
- {@link Session#LATITUDE $Latitude} - Invalid value will be set to
* "NaN"
*
- {@link Session#LONGITUDE $Longitude} - Invalid value will be set to
* "NaN"
*
* If values are provided for any other fixed session properties they will
* be ignored.
*
* @param filter the session filter
*
* @param properties the properties to change. Each key should be a valid
* session property key (see {@link Session}). Further, keys starting
* with '$' should be one of the allowed fixed session property keys
* listed above. If the value is null, any existing user-defined
* session property with the key will be removed. Fixed session
* properties cannot be removed. If the value is non-null, it will be
* used to set the value of the the session property with the given
* key, adding it if necessary.
*
* @return a CompletableFuture that completes when a response is received
* from the server.
*
*
* If the sessions properties were updated for the sessions that
* satisfied the filter, the CompletableFuture will complete
* successfully with a {@link SessionFilterOperationResult}.
*
*
* 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} and
* {@code VIEW_SESSION} permission;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.0
*/
CompletableFuture setSessionProperties(
String filter, Map properties);
/**
* The callback interface for
* {@link ClientControl#getSessionProperties(SessionId, Collection, SessionPropertiesCallback)}
* .
*
* @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 SessionPropertiesCallback extends Callback {
/**
* Called to return requested session properties.
*
* @param sessionId the session identifier
*
* @param properties map of the requested session property values
*/
void onReply(
SessionId sessionId,
Map properties);
/**
* Called to indicate that the session indicated in a request is not
* known by the server.
*
* @param sessionId the requested session identifier
*/
void onUnknownSession(SessionId sessionId);
}
/**
* Contextual callback interface for
* {@link ClientControl#getSessionProperties(SessionId, Collection, Object, SessionPropertiesContextCallback)}
* .
*
* Used to associate some arbitrary context object with each call.
*
* @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
interface SessionPropertiesContextCallback extends ContextCallback {
/**
* Called to return requested session properties.
*
* @param context the context object supplied when making the call. May
* be {@code null}
*
* @param sessionId the session identifier
*
* @param properties a map of the requested session property values
*/
void onReply(
C context,
SessionId sessionId,
Map properties);
/**
* Called to indicate that the session indicated in a request is not
* known by the server.
*
* @param context the context object supplied when making the call. May
* be {@code null}
*
* @param sessionId the requested session identifier
*/
void onUnknownSession(C context, SessionId sessionId);
}
/**
* Register a handler for client queue threshold events.
*
* Each control session can register a single handler. When the handler is
* no longer required, it may be closed using the {@link Registration}
* provided by the CompletableFuture result. To set a different handler the
* current handler must first be closed. For each event, the server will
* select a single handler.
*
* The control session may choose to act upon queue events for a session by
* activating conflation for the session.
*
* @param handler the queue handler to set
*
* @return a CompletableFuture that completes when the handler has been
* registered, returning a {@link Registration} which can be used to
* unregister the handler.
*
* 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 SessionClosedException} – if the session is
* closed;
*
*
- {@link HandlerConflictException} – if the session has
* already registered a queue event handler;
*
*
- {@link PermissionsException} – if the session does
* not have {@code REGISTER_HANDLER} permission;
*
*
- {@link PermissionsException} – if the session does
* not have {@code VIEW_SESSION} permission.
*
*
* @since 6.0
*/
CompletableFuture setQueueEventHandler(QueueEventStream handler);
/**
* Register a handler for client queue threshold events.
*
* Each control session can register a single handler. (See
* {@link QueueEventHandler#onActive(RegisteredHandler)}). A handler may be
* closed (using {@link RegisteredHandler#close()}) if no longer required.
* To set a different handler the current handler must first be closed. For
* each event, the server will select a single handler.
*
* The control session may choose to act upon queue events for a session by
* activating conflation for the session.
*
* @param handler the queue handler to set
*
* @deprecated since 6.7
*
* The CompletableFuture-based alternative
* {@link #setQueueEventHandler(QueueEventStream)} should be
* preferred since it provides better error reporting.
*/
@Deprecated
void setQueueEventHandler(QueueEventHandler handler);
/**
* Close a client session.
*
* @param sessionId identifies the client session to close
*
* @return a CompletableFuture that completes when a response is received
* from the server.
*
*
* If the identified session was closed, 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 NoSuchSessionException} – if the identified
* session was closed before the response was delivered;
*
*
- {@link PermissionsException} – if the calling
* session does not have {@code MODIFY_SESSION} and
* {@code VIEW_SESSION} permissions;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.0
*/
CompletableFuture close(SessionId sessionId);
/**
* Close all client sessions matching a given session filter.
*
* @param filter matches the set of client sessions to close. For details on
* specifying session filters see {@link Session}.
*
* @return a {@link CompletableFuture} that completes when the matching
* sessions have been closed.
*
* If the CompletableFuture completes normally then it returns a
* {@link SessionFilterOperationResult} which provides the number of
* sessions that matched the filter and have been closed.
*
* 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 {@code filter}
* was invalid;
*
*
- {@link PermissionsException} – if the calling
* session does not have {@code MODIFY_SESSION} and
* {@code VIEW_SESSION} permissions;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.5
*/
CompletableFuture close(String filter);
/**
* Close a client session.
*
* The CompletableFuture-based alternative {@link #close(SessionId)} should
* be preferred since it provides better error reporting.
*
* @param sessionId identifies the client session to close
*
* @param callback the operation callback
*
* @since 5.5
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void close(SessionId sessionId, ClientCallback callback);
/**
* Close a client session with a contextual callback.
*
* The CompletableFuture-based alternative {@link #close(SessionId)} should
* be preferred since it provides better error reporting.
*
* @param the context type
*
* @param sessionId identifies the client session to close
*
* @param context the context object to pass to the callback
*
* @param callback the operation callback
*
* @since 5.5
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void close(
SessionId sessionId,
C context,
ClientContextCallback callback);
/**
* Control client queue conflation.
*
* Each session begins with conflation enabled or disabled based on the
* queue configuration of the connector it is using. This method allows
* conflation to be enabled or disabled for specific sessions at runtime.
*
* Conflation is the process of merging or discarding topic updates queued
* for a session to reduce the server memory footprint and network data.
* Conflation needs to be enabled for a session and a policy configured for
* the topic to have an effect. Policies are configured on a per-topic
* basis using the
* {@link com.pushtechnology.diffusion.client.topics.details.TopicSpecification#CONFLATION
* topic property CONFLATION}.
*
* @param sessionId identifies the client session
*
* @param conflate {@code true} to enable conflation, {@code false} to
* disable conflation
*
* @return a CompletableFuture that completes when a response is received
* from the server.
*
*
* If the conflation policy was updated for the identified session,
* 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 NoSuchSessionException} – if the identified
* session was closed before the response was delivered;
*
*
- {@link PermissionsException} – if the calling
* session does not have {@code MODIFY_SESSION} and
* {code VIEW_SESSION} permissions;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.0
*/
CompletableFuture setConflated(
SessionId sessionId,
boolean conflate);
/**
* Control client queue conflation.
*
* Each session begins with conflation enabled or disabled based on the
* queue configuration of the connector it is using. This method allows
* conflation to be enabled or disabled for a set of sessions matching a
* filter at runtime. For more detail on specifying session filters see
* {@link Session}.
*
* Conflation is the process of merging or discarding topic updates queued
* for a session to reduce the server memory footprint and network data.
* Conflation needs to be enabled for a session and a policy configured for
* the topic to have an effect. Policies are configured on a per-topic
* basis using the
* {@link com.pushtechnology.diffusion.client.topics.details.TopicSpecification#CONFLATION
* topic property CONFLATION}.
*
* @param filter identifies the client sessions
*
* @param conflate {@code true} to enable conflation, {@code false} to
* disable conflation
*
* @return a CompletableFuture that completes when a response is received
* from the server. It contains a
* {@link SessionFilterOperationResult} with the number of sessions
* that matched the filter.
*
*
* If the conflation policy was updated for the identified sessions,
* the CompletableFuture will complete successfully. The result type
* is a {@link SessionFilterOperationResult} rather than Integer to
* provide forward compatibility with future iterations of this API
* that may provide additional information.
*
*
* 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 {@code filter}
* parameter could not be parsed;
*
*
- {@link PermissionsException} – if the calling
* session does not have {@code MODIFY_SESSION} or
* {@code VIEW_SESSION} permissions;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
* @since 6.5
*/
CompletableFuture setConflated(
String filter,
boolean conflate);
/**
* Control client queue conflation.
*
* Each session begins with conflation enabled or disabled based on the
* queue configuration of the connector it is using. This method allows
* conflation to be enabled or disabled for specific sessions at runtime.
*
* Conflation is the process of merging or discarding topic updates queued
* for a session to reduce the server memory footprint and network data.
* Conflation needs to be enabled for a session and a policy configured for
* the topic to have an effect. Policies are configured on a per-topic
* basis using the
* {@link com.pushtechnology.diffusion.client.topics.details.TopicSpecification#CONFLATION
* topic property CONFLATION}.
*
* The CompletableFuture-based alternative
* {@link #setConflated(SessionId, boolean)} should be preferred since it
* provides better error reporting.
*
* @param sessionId identifies the client session
*
* @param conflate {@code true} to enable conflation, {@code false} to
* disable conflation
*
* @param callback the operation callback
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void setConflated(
SessionId sessionId,
boolean conflate,
ClientCallback callback);
/**
* Control client queue conflation with a contextual callback.
*
* The CompletableFuture-based alternative
* {@link #setConflated(SessionId, boolean)} should be preferred since it
* provides better error reporting.
*
* @param the context type
*
* @param sessionId identifies the client session
*
* @param conflate {@code true} to enable conflation, {@code false} to
* disable conflation
*
* @param context the context to pass to the callback
*
* @param callback the operation callback
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void setConflated(
SessionId sessionId,
boolean conflate,
C context,
ClientContextCallback callback);
/**
* Restore a {@link SessionId} from a string.
*
*
* This method allows a {@code SessionId} to be converted to a string with
* {@link SessionId#toString()} and later recovered from the string. This is
* a client operation. A session that has been closed will not be recreated.
*
* @param sessionIdAsString a string, previously created with
* {@link SessionId#toString()}
*
* @return the {@code SessionId}
*
* @throws IllegalArgumentException if the string was not generated by
* {@link SessionId#toString()}
*
* @since 5.2
*
* @deprecated since 6.7
*
* Use {@link Diffusion#sessionIdFromString} which allows the
* method to be statically imported. This method will be removed
* in a future release.
*/
@Deprecated
SessionId sessionIdFromString(String sessionIdAsString)
throws IllegalArgumentException;
/**
* Changes the assigned roles of another session.
*
* Initially a session has a set of roles assigned during authentication.
* The set of assigned roles can be obtained from the session's $Roles
* {@link Session session} property.
*
* When a session's assigned roles change, its $Roles property changes
* accordingly. Changing the assigned roles can change the READ_TOPIC
* permissions granted to the session. The session's subscriptions will be
* updated accordingly.
*
* The same role must not occur in both {@code rolesToRemove} and
* {@code rolesToAdd} sets. Either set can be an empty set but not both.
*
* @param sessionId identifies the client session for which the change will be
* applied
* @param rolesToRemove a set of roles to be removed from the session. If
* one or more roles from the list are not currently assigned, they
* are ignored.
* @param rolesToAdd a set of roles to be added to the session. If one or
* more roles from the list are already assigned, they are ignored.
* @return a {@link CompletableFuture} that completes when session roles have
* been changed.
*
* If the CompletableFuture completes normally then it indicates
* that the specified role changes have been applied to the session.
*
* 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} and
* {@code VIEW_SESSION} permission;
*
*
- {@link NoSuchSessionException} – if there is no session
* with the given {@code sessionId};
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
* @throws IllegalArgumentException if the same role occurs in both
* {@code rolesToRemove} and {@code rolesToAdd} sets or if both sets
* are empty
* @since 6.2
*/
CompletableFuture changeRoles(
SessionId sessionId,
Set rolesToRemove,
Set rolesToAdd) throws IllegalArgumentException;
/**
* Allows a session to change the assigned roles of all sessions that
* satisfy a given session filter.
*
* Initially a session has a set of roles assigned during authentication.
* A current roles set can be obtained from the $Roles {@link Session}
* property.
*
* When a set of session roles changes, its $Roles property changes
* accordingly. As a role can constrain 'topic' permissions, session
* subscriptions are re-evaluated based on the new roles set.
*
* The same role must not occur in both {@code rolesToRemove} and
* {@code rolesToAdd} sets. Either set can be an empty set but not both.
*
* @param filter identifies the set of client sessions for which the change
* will be applied. For details on how to specify session filters see
* {@link Session}.
* @param rolesToRemove a set of roles to be removed from the session. If
* one or more roles from the list are not currently assigned, they
* are ignored.
* @param rolesToAdd a set of roles to be added to the session. If one or
* more roles from the list are already assigned, they are ignored.
* @return a {@link CompletableFuture} that completes when session roles have
* been changed.
*
* If the CompletableFuture completes normally then it returns
* an integer value which represents a number of sessions that have
* matched the filter and for which the specified role changes have
* been applied.
*
* 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} and
* {@code VIEW_SESSION} permissions;
*
*
- {@link SessionClosedException} – if the calling session
* is closed.
*
*
- {@link InvalidFilterException} – if the {@code filter}
* parameter could not be parsed;
*
* @throws IllegalArgumentException if the same role occurs in both
* {@code rolesToRemove} and {@code rolesToAdd} sets or if both sets
* are empty
* @since 6.2
*/
CompletableFuture changeRoles(
String filter,
Set rolesToRemove,
Set rolesToAdd) throws IllegalArgumentException;
/**
* Callback interface for
* {@link ClientControl#close(SessionId, ClientCallback) close}, and
* {@link ClientControl#setConflated(SessionId, boolean, ClientCallback)
* setConflated}.
*
* Provides notifications of whether the requested operation was handled by
* the server.
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface ClientCallback extends
com.pushtechnology.diffusion.client.features.Callback {
/**
* This is called to indicate that a requested operation has been
* handled by the server.
*/
void onComplete();
/**
* Default implementation of {@link ClientCallback}.
*
* This simply logs onComplete calls at 'debug' level. The method may be
* overridden to perform some more specific action.
*/
class Default
extends
com.pushtechnology.diffusion.client.features.Callback.Default
implements ClientCallback {
private static final Logger LOG =
getLogger(ClientCallback.Default.class);
@Override
public void onComplete() {
LOG.debug("{} - Client operation complete", this);
}
}
}
/**
* Contextual version of {@link ClientCallback} used with
* {@link ClientControl#close(SessionId, Object, ClientContextCallback)
* close} and
* {@link ClientControl#setConflated(SessionId, boolean, Object, ClientContextCallback)
* setConflated}.
*
* Attaches an arbitrary context object to callback notifications.
*
* @param the context 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 ClientContextCallback extends
com.pushtechnology.diffusion.client.features.ContextCallback {
/**
* This is called to indicate that a requested operation has been
* handled by the server.
*/
void onComplete(C context);
/**
* Default implementation of {@link ClientContextCallback}.
*
* This simply logs onComplete calls at 'debug' level. The method may be
* overridden to perform some more specific action.
*
* @param context object type
*/
class Default
extends
com.pushtechnology.diffusion.client.features.ContextCallback.Default
implements ClientContextCallback {
private static final Logger LOG =
getLogger(ClientContextCallback.Default.class);
@Override
public void onComplete(C context) {
LOG.debug(
"{} - Client operation complete, context={}",
this,
context);
}
}
}
/**
* Handler for client queue events.
*
* An implementation can be registered using
* {@link ClientControl#setQueueEventHandler(QueueEventStream)}.
*
* @since 6.0
*/
interface QueueEventStream extends Stream {
/**
* The configured upper threshold for a client's queue has been reached.
*
* @param sessionId the client session identifier
*
* @param policy the message queue policy
*/
void onUpperThresholdCrossed(
SessionId sessionId,
MessageQueuePolicy policy);
/**
* The configured lower threshold for a client's queue has been reached.
*
* @param sessionId the client session identifier
*
* @param policy the message queue policy
*/
void onLowerThresholdCrossed(
SessionId sessionId,
MessageQueuePolicy policy);
/**
* This provides a default implementation of {@link QueueEventHandler}.
*
* This simply logs events at debug level and should only be used for
* diagnostic purposes. This may be extended to implement the
* notifications you wish to act upon.
*/
class Default extends Stream.Default
implements QueueEventStream {
private static final Logger LOG =
LoggerFactory
.getLogger(QueueEventHandler.Default.class);
@Override
public void onUpperThresholdCrossed(
final SessionId sessionId,
final MessageQueuePolicy policy) {
LOG.debug(
"{} - Session {} with policy {} : " +
"Upper queue threshold crossed",
this,
sessionId,
policy);
}
@Override
public void onLowerThresholdCrossed(
final SessionId sessionId,
final MessageQueuePolicy policy) {
LOG.debug(
"{} - Session {} with policy {} : " +
"Lower queue threshold crossed",
this,
sessionId,
policy);
}
}
}
/**
* Handler for client queue events.
*
* An implementation can be registered using
* {@link ClientControl#setQueueEventHandler(QueueEventHandler)}.
*
* @deprecated since 6.7
*
* Use {@link QueueEventStream} instead.
*/
@Deprecated
interface QueueEventHandler extends
com.pushtechnology.diffusion.client.features.ServerHandler {
/**
* The configured upper threshold for a client's queue has been reached.
*
* @param sessionId the client session identifier
*
* @param policy the message queue policy
*/
void onUpperThresholdCrossed(
SessionId sessionId,
MessageQueuePolicy policy);
/**
* The configured lower threshold for a client's queue has been reached.
*
* @param sessionId the client session identifier
*
* @param policy the message queue policy
*/
void onLowerThresholdCrossed(
SessionId sessionId,
MessageQueuePolicy policy);
/**
* This provides a default implementation of {@link QueueEventHandler}.
*
* This simply logs events at debug level and should only be used for
* diagnostic purposes. This may be extended to implement the
* notifications you wish to act upon.
*/
class Default
extends
com.pushtechnology.diffusion.client.features.ServerHandler.Default
implements QueueEventHandler {
private static final Logger LOG =
LoggerFactory
.getLogger(QueueEventHandler.Default.class);
@Override
public void onUpperThresholdCrossed(
final SessionId sessionId,
final MessageQueuePolicy policy) {
LOG.debug(
"{} - Session {} with policy {} : " +
"Upper queue threshold crossed",
this,
sessionId,
policy);
}
@Override
public void onLowerThresholdCrossed(
final SessionId sessionId,
final MessageQueuePolicy policy) {
LOG.debug(
"{} - Session {} with policy {} : " +
"Lower queue threshold crossed",
this,
sessionId,
policy);
}
}
}
/**
* The handler for session properties listener notifications.
*
* This is used along with
* {@link ClientControl#setSessionPropertiesListener(SessionPropertiesStream, String...)}
* to obtain notifications for client sessions.
*
* Callbacks with a {@code properties} parameter provide a map of the
* property values requested when registering the listener.
*
* @since 6.0
*/
interface SessionPropertiesStream extends Stream {
/**
* Event type.
*/
enum EventType {
/**
* One or more relevant session properties have been updated.
*/
UPDATED,
/**
* Session has reconnected.
*/
RECONNECTED,
/**
* Use in a clustered configuration to indicate that the session
* failed over from another server.
*/
FAILED_OVER,
/**
* Session has disconnected.
*/
DISCONNECTED
}
/**
* Notification that a new client session has been opened.
*
* When the listener is registered, this will be called for all existing
* sessions. It will then be called for every new session that opens
* whilst the listener is registered.
*
* This will be called for every client session regardless of requested
* session properties.
*
* @param sessionId the session identifier
*
* @param properties the map of requested session property values. This
* can be empty if no properties were requested. If a requested
* property did not exist, it will not be present in the map.
*/
void onSessionOpen(
SessionId sessionId,
Map properties);
/**
* Notification of a session event that can result in a change of
* properties.
*
* @param sessionId the client session id
*
* @param eventType indicates the type of event
*
* @param properties the map of current requested property values. This
* can be empty if no properties were requested. If a requested
* property did not exist, it will not be present in the map.
*
* @param previousValues a map of the previous values of keys that have
* changed. This will only contain keys that have changed and not
* the whole required property set. This can be empty if an event
* is being reported that did not result in the change of any of
* the required properties. When a new property is added, the
* value in this map will be null. When a property is removed, it
* will have a value in this map but not in {@code properties}.
*/
void onSessionEvent(
SessionId sessionId,
EventType eventType,
Map properties,
Map previousValues);
/**
* Notification that a client session has closed.
*
* This will be called for every client that closes whilst the listener
* is registered regardless of requested session properties.
*
* @param sessionId the session identifier of the client that has closed
*
* @param properties the map of requested property values at the point
* when the session was closed. This can be empty if no
* properties were requested. If a requested property did not
* exist, it will not be present in the map.
*
* @param closeReason why the session was closed
*/
void onSessionClose(
SessionId sessionId,
Map properties,
CloseReason closeReason);
/**
* This provides a default implementation of
* {@link SessionPropertiesListener} which will simply log session
* properties callbacks at debug level. This should only be used for
* diagnostic purposes.
*/
class Default extends Stream.Default
implements SessionPropertiesStream {
private static final Logger LOG =
LoggerFactory
.getLogger(SessionPropertiesListener.Default.class);
@Override
public void onSessionOpen(
SessionId sessionId,
Map properties) {
LOG.debug(
"{} - Client session {} opened : {}",
this,
sessionId,
properties);
}
@Override
public void onSessionEvent(
SessionId sessionId,
EventType eventType,
Map properties,
Map previousValues) {
LOG.debug(
"{} - Client session {} event : {}, Properties={}, Previous Values={}",
this,
sessionId,
eventType,
properties,
previousValues);
}
@Override
public void onSessionClose(
SessionId sessionId,
Map properties,
CloseReason closeReason) {
LOG.debug(
"{} - Client session {} closed - {} : {}",
this,
sessionId,
closeReason,
properties);
}
}
}
/**
* The server's view of why a client session was closed.
*/
enum CloseReason {
/**
* The connection to the client was lost - possibly dropped by the
* client. Recoverable.
*
* A client may be closed for many reasons that are presented as
* CONNECTION_LOST.
*
* During connection the connection can be lost. The server might have
* received a connection or reconnection request from a client already
* connected. The server might have received a reconnection request
* without a session Id. The connection may not have been authorised
* because the credentials are wrong. The maximum number of clients
* might already be connected.
*
* Once connected the connection can be lost for different reasons. If
* the client closes its connection while the server is writing a
* message to the client. With the chunked encoding based connection the
* HTTP response is completed by the server. If the client does not open
* a new request within a timeout the client will be closed. If a poll
* request times out and the server finds that the connection has
* already been closed by the client.
*/
CONNECTION_LOST,
/**
* An unexpected IO Exception occurred. Recoverable.
*
* While trying to perform an I/O operation an exception was generated.
* This often means that a read was attempted from a closed TCP
* connection.
*
* When handling SSL connections if there is a problem encrypting or
* decrypting a message the client will be closed for this reason.
*/
IO_EXCEPTION,
/**
* The client had become unresponsive.
*
* The client has either failed to respond to a ping message in a timely
* manner or the client has failed to open an HTTP poll for messages.
* The client does not appear to be receiving messages.
*/
CLIENT_UNRESPONSIVE,
/**
* The maximum outbound queue size was reached for the client. Not
* recoverable.
*
* Messages sent to the client are placed in a queue. This queue has a
* maximum allowed size. If the queue limit is reached the client is
* closed and the queue discarded. The queue is intended to protect
* against slow consumers, reaching the queue limit is taken to mean
* that the client cannot keep up with the number of messages sent to
* it.
*/
MESSAGE_QUEUE_LIMIT_REACHED,
/**
* The client requested close. Not recoverable.
*/
CLOSED_BY_CLIENT,
/**
* The client sent a message that exceeded the maximum message size that
* can be processed by the server.
*
* The server has a maximum message size that it can process on any
* single connector. If a client sends a message larger than this the
* server is unable to process it. When this happens the message is
* discarded and the client is closed.
*/
MESSAGE_TOO_LARGE,
/**
* An internal error occurred.
*
* An unexpected internal error has occurred. The server logs will
* contain more detail.
*/
INTERNAL_ERROR,
/**
* An inbound message with an invalid format was received.
*
* A message received by the server is not a valid Diffusion message.
* The server is unable to process this and closes the client that sent
* it.
*/
INVALID_INBOUND_MESSAGE,
/**
* The client connection was aborted by the server, possibly because the
* connection was disallowed.
*
* This is may be because the connection was disallowed. Abort messages
* are also sent to clients that have unrecognised client IDs. This may
* be because the server closed the client previously but the client is
* unaware of this and tried to continue interacting with the server.
*/
ABORTED,
/**
* Loss of messages from the client has been detected. For example,
* whilst waiting for the arrival of missing messages in a sequence of
* messages a timeout has occurred.
*
* HTTP based transports use multiple TCP connections. This can cause
* the messages to be received out of order. To reorder the messages
* those sent to the server may contain a sequence number indicating the
* correct order.
*
* If a message is received out of order there is a short time for the
* earlier messages to be received. If the messages are not received in
* this time the client is closed.
*
* Missing, invalid or duplicate sequence numbers will also close the
* client for this reason.
*
* This cannot be recovered from as the client and the server are in
* inconsistent states.
*/
LOST_MESSAGES,
/**
* The server is closing down.
*
* The client was closed as part of the server shutdown process.
*
* @deprecated Since 6.6. This event is not emitted during server
* shutdown and will be removed in a future release.
*/
@Deprecated
SERVER_CLOSING,
/**
* Closed by a client session.
*
* A control session initiated the client close.
*/
CLOSED_BY_CONTROLLER,
/**
* The session has failed over to a different Diffusion server.
*
* The session is still open but is now connected to a different
* Diffusion server. This server has evicted its view of the session
* from its set of local sessions.
*
* @since 5.8
*/
FAILED_OVER
}
/**
* Result of ClientControl operations that identify sessions using a client
* filter and provide a result through a {@link CompletableFuture}.
*
* @since 6.5
*/
interface SessionFilterOperationResult {
/**
* @return the number of sessions that were selected by the provided
* filter.
*/
int selected();
}
}