Package com.pushtechnology.diffusion.client.features.control.clients

Interface ClientControl

All Superinterfaces:
Feature
public interface ClientControl extends Feature
This feature provides the ability for a client session to control other client sessions.

It allows for notifications of client session events as well as the ability to manage client sessions (forcibly closing them etc).

It also provides the ability to monitor session locks.

Access control

A session must have VIEW_SESSION permission to be able to listen for notifications using addSessionEventListener(com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventStream, com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventParameters) or setSessionPropertiesListener(com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionPropertiesStream, java.lang.String...), or get properties of sessions or listen for queue events.

In addition, REGISTER_HANDLER permission is required to set a session event listener, a session property listener, or queue event handler.

In order to perform operations that change a specific session's state (such as conflating, closing sessions, or changing roles), MODIFY_SESSION permission is required.

Accessing the feature

This feature may be obtained from a session as follows: 
 
 ClientControl clientControl = session.feature(ClientControl.class);
Since:
5.0
Author:
DiffusionData Limited

  • Method Details

    • addSessionEventListener

      CompletableFuture<Registration> addSessionEventListener(ClientControl.SessionEventStream listener, ClientControl.SessionEventParameters parameters)
      Register a listener that will be notified of client session events.

      These events may occur when a client session is opened, becomes disconnected, reconnects, fails over, or is closed. Events may also occur if any of the session properties of the client session change as a result of a call to setSessionProperties(com.pushtechnology.diffusion.client.session.SessionId, java.util.Map<java.lang.String, java.lang.String>).

      When a listener is first added, by default, it will be called with STATE events for all currently open sessions. The amount of data transferred from the server is proportional to the number of connected clients and is potentially large, especially if session properties are requested. To mitigate this the caller can choose to only receive events for sessions started after a specified time (e.g. from now), in which case events will only be received for sessions that start after that time.

      A control session can register any number of listeners with different parameters, but the cost in network traffic should be carefully considered.

      When a listener is no longer required, it may be closed using the Registration provided by the CompletableFuture result.

      The parameters parameter is used to define the level of event detail required.

      Parameters:
      listener - the listener to be called with session event notifications
      parameters - a ClientControl.SessionEventParameters object defining the level of event detail required.

      ClientControl.SessionEventParameters.DEFAULT may be provided to notify events for all sessions, including those that already exist, but returning no session properties.

      Returns:
      a CompletableFuture that completes when the listener has been registered, returning a Registration which can be used to unregister the listener.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.11

    • setSessionPropertiesListener

      @Deprecated CompletableFuture<Registration> setSessionPropertiesListener(ClientControl.SessionPropertiesStream listener, String... requiredProperties)
      Deprecated.
      since 6.11

      Use the new addSessionEventListener(com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventStream, com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventParameters), which provides greater functionality and reports on sessions at all cluster members. This method will be removed in a future release.

      Register a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated.

      This only notifies sessions connecting to the same server as the current session and therefore if the Diffusion system is operating as a cluster then the only way to receive notifications for sessions at all cluster members would be to connect separate sessions (and listeners) to each cluster member. When connecting to a cluster it is recommended that the addSessionEventListener(com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventStream, com.pushtechnology.diffusion.client.features.control.clients.ClientControl.SessionEventParameters) method is used instead.

      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 requiredProperties parameter.

      Each control session can register a single listener. When the listener is no longer required, it may be closed using the Registration provided by the CompletableFuture result. To change the listener, the previous listener must first be closed.

      The 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.

      Parameters:
      listener - the listener to be called with session notifications
      requiredProperties - a list of required property keys. See Session for a full list of available fixed property keys. To request no properties supply an empty list. To request all fixed properties include Session.ALL_FIXED_PROPERTIES as a key. In this case any other fixed property keys would be ignored. To request all user properties include Session.ALL_USER_PROPERTIES as a key. In this case any other user properties are ignored.
      Returns:
      a CompletableFuture that completes when the listener has been registered, returning a Registration which can be used to unregister the listener.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • getSessionProperties

      CompletableFuture<Map<String,String>> getSessionProperties(SessionId sessionId, Collection<String> requiredProperties)
      Query the server for property values of a specified client session.
      Parameters:
      sessionId - identifies the client session
      requiredProperties - a list of required property keys. See Session for a full list of available fixed property keys. To request no properties supply an empty list. To request all fixed properties include Session.ALL_FIXED_PROPERTIES as a key. In this case any other fixed property keys would be ignored. To request all user properties include Session.ALL_USER_PROPERTIES as a key. In this case any other user properties are ignored.
      Returns:
      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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.5

    • setSessionProperties

      CompletableFuture<Map<String,String>> setSessionProperties(SessionId sessionId, Map<String,String> properties)
      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 :-

      • $Country - will be normalised to upper case
      • $Language - will be normalised to lower case
      • $Latitude - Invalid value will be set to "NaN"
      • $Longitude - Invalid value will be set to "NaN"
      If values are provided for any other fixed session properties they will be ignored.
      Parameters:
      sessionId - identifies the client session
      properties - the properties to change. Each entry in the map is a property name and the new value. If the value is 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).
      Returns:
      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 null to indicate that they do not have an old value.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • setSessionProperties

      CompletableFuture<ClientControl.SessionFilterOperationResult> setSessionProperties(String filter, Map<String,String> 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:

      • $Country - will be normalised to upper case
      • $Language - will be normalised to lower case
      • $Latitude - Invalid value will be set to "NaN"
      • $Longitude - Invalid value will be set to "NaN"
      If values are provided for any other fixed session properties they will be ignored.
      Parameters:
      filter - the session filter
      properties - the properties to change. Each key should be a valid session property key (see 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.
      Returns:
      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 ClientControl.SessionFilterOperationResult.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • setQueueEventHandler

      CompletableFuture<Registration> setQueueEventHandler(ClientControl.QueueEventStream handler)
      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 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.

      Parameters:
      handler - the queue handler to set
      Returns:
      a CompletableFuture that completes when the handler has been registered, returning a Registration which can be used to unregister the handler.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • close

      CompletableFuture<?> close(SessionId sessionId)
      Close a client session.
      Parameters:
      sessionId - identifies the client session to close
      Returns:
      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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • close

      CompletableFuture<ClientControl.SessionFilterOperationResult> close(String filter)
      Close all client sessions matching a given session filter.
      Parameters:
      filter - matches the set of client sessions to close. For details on specifying session filters see Session.
      Returns:
      a CompletableFuture that completes when the matching sessions have been closed.

      If the CompletableFuture completes normally then it returns a ClientControl.SessionFilterOperationResult which provides the number of sessions that matched the filter and have been closed.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.5

    • setConflated

      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 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 topic property CONFLATION.

      Parameters:
      sessionId - identifies the client session
      conflate - true to enable conflation, false to disable conflation
      Returns:
      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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.0

    • setConflated

      CompletableFuture<ClientControl.SessionFilterOperationResult> 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 a set of sessions matching a filter at runtime. For more detail on specifying session filters see 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 topic property CONFLATION.

      Parameters:
      filter - identifies the client sessions
      conflate - true to enable conflation, false to disable conflation
      Returns:
      a CompletableFuture that completes when a response is received from the server. It contains a ClientControl.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 ClientControl.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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.5

    • changeRoles

      CompletableFuture<?> changeRoles(SessionId sessionId, Set<String> rolesToRemove, Set<String> rolesToAdd) 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 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 rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

      Parameters:
      sessionId - identifies the client session for which the change will be applied
      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.
      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.
      Returns:
      a 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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Throws:
      IllegalArgumentException - if the same role occurs in both rolesToRemove and rolesToAdd sets or if both sets are empty
      Since:
      6.2

    • changeRoles

      CompletableFuture<Integer> changeRoles(String filter, Set<String> rolesToRemove, Set<String> 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 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 rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

      Parameters:
      filter - identifies the set of client sessions for which the change will be applied. For details on how to specify session filters see Session.
      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.
      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.
      Returns:
      a 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 CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Throws:
      IllegalArgumentException - if the same role occurs in both rolesToRemove and rolesToAdd sets or if both sets are empty
      Since:
      6.2

    • getSessionLock

      CompletableFuture<ClientControl.SessionLockDetails> getSessionLock(String lockName)
      Returns details of the session (if any) that holds a named session lock.
      Parameters:
      lockName - the lock name
      Returns:
      a CompletableFuture that completes with details of the named lock.

      If the CompletableFuture completes normally then it returns the details of the session that currently holds the lock, or null if no session holds the named lock.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.12

    • getSessionLocks

      CompletableFuture<Map<String,ClientControl.SessionLockDetails>> getSessionLocks()
      Returns details of all session locks currently held.
      Returns:
      a CompletableFuture that completes with details of all session locks that are currently held.

      If the CompletableFuture completes normally then it returns a map of session locks keyed on the lock name where the value identifies the session currently holding the lock. If there are no session locks currently held by anybody this will return an empty map.

      Otherwise, the CompletableFuture will complete exceptionally with a CompletionException. Common reasons for failure, listed by the exception reported as the cause, include:

      Since:
      6.12