ClientControl (diffusion-api 6.11.1 API)

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).
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 session's state (such as conflating, closing the session, or changing roles), both VIEW_SESSION and MODIFY_SESSION permissions are 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

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`ClientControl.ClientCallback` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`ClientControl.ClientContextCallback<C>` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static class`	`ClientControl.CloseReason` The server's view of why a client session was closed.
`static interface`	`ClientControl.QueueEventHandler` Deprecated. since 6.7 Use `ClientControl.QueueEventStream` instead.
`static interface`	`ClientControl.QueueEventStream` Handler for client queue events.
`static interface`	`ClientControl.SessionEventParameters` Provides parameters which specify the level of detail required by a `ClientControl.SessionEventStream` registered using `setSessionEventListener`.
`static interface`	`ClientControl.SessionEventStream` The stream to receive for session event listener notifications.
`static interface`	`ClientControl.SessionFilterOperationResult` Result of ClientControl operations that identify sessions using a client filter and provide a result through a `CompletableFuture`.
`static interface`	`ClientControl.SessionPropertiesCallback` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`ClientControl.SessionPropertiesContextCallback<C>` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`static interface`	`ClientControl.SessionPropertiesStream` 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 sessions at all cluster members. This interface will be removed in a future release.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`CompletableFuture<Registration>`	`addSessionEventListener(ClientControl.SessionEventStream listener, ClientControl.SessionEventParameters parameters)` Register a listener that will be notified of `client session events`.
`CompletableFuture<?>`	`changeRoles(SessionId sessionId, Set<String> rolesToRemove, Set<String> rolesToAdd)` Changes the assigned roles of another session.
`CompletableFuture<Integer>`	`changeRoles(String filter, Set<String> rolesToRemove, Set<String> rolesToAdd)` Allows a session to change the assigned roles of all sessions that satisfy a given session filter.
`CompletableFuture<?>`	`close(SessionId sessionId)` Close a client session.
`<C> void`	`close(SessionId sessionId, C context, ClientControl.ClientContextCallback<C> callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`void`	`close(SessionId sessionId, ClientControl.ClientCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<ClientControl.SessionFilterOperationResult>`	`close(String filter)` Close all client sessions matching a given session filter.
`CompletableFuture<Map<String,String>>`	`getSessionProperties(SessionId sessionId, Collection<String> requiredProperties)` Query the server for property values of a specified client session.
`<C> void`	`getSessionProperties(SessionId sessionId, Collection<String> requiredProperties, C context, ClientControl.SessionPropertiesContextCallback<C> callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`void`	`getSessionProperties(SessionId sessionId, Collection<String> requiredProperties, ClientControl.SessionPropertiesCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`SessionId`	`sessionIdFromString(String sessionIdAsString)` Deprecated. since 6.7 Use `Diffusion.sessionIdFromString(java.lang.String)` which allows the method to be statically imported. This method will be removed in a future release.
`CompletableFuture<?>`	`setConflated(SessionId sessionId, boolean conflate)` Control client queue conflation.
`<C> void`	`setConflated(SessionId sessionId, boolean conflate, C context, ClientControl.ClientContextCallback<C> callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`void`	`setConflated(SessionId sessionId, boolean conflate, ClientControl.ClientCallback callback)` Deprecated. since 6.7 Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
`CompletableFuture<ClientControl.SessionFilterOperationResult>`	`setConflated(String filter, boolean conflate)` Control client queue conflation.
`void`	`setQueueEventHandler(ClientControl.QueueEventHandler handler)` Deprecated. since 6.7 The CompletableFuture-based alternative `setQueueEventHandler(QueueEventStream)` should be preferred since it provides better error reporting.
`CompletableFuture<Registration>`	`setQueueEventHandler(ClientControl.QueueEventStream handler)` Register a handler for client queue threshold events.
`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.
`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.
`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.

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature
getSession

- Method Detail
  - 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:
    
    SessionClosedException – if the session is closed;
    ErrorReportsException – if the session filter specified in the parameters was invalid;
    PermissionsException – if the session does not have REGISTER_HANDLER and VIEW_SESSION permissions.
    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:
    
    SessionClosedException – if the session is closed;
    HandlerConflictException – if the session has already registered a session properties listener;
    PermissionsException – if the session does not have REGISTER_HANDLER and VIEW_SESSION permissions.
    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:
    
    NoSuchSessionException – if the identified session was closed before the response was delivered;
    PermissionsException – if the calling session does not have the VIEW_SESSION permission;
    SessionClosedException – if the calling session is closed.
    Since:
    
    6.5
  - getSessionProperties
```
@Deprecated
void getSessionProperties(SessionId sessionId,
                                      Collection<String> requiredProperties,
                                      ClientControl.SessionPropertiesCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    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.
    
    callback - called with the response
    
    Since:
    
    5.6
  - getSessionProperties
```
@Deprecated
<C> void getSessionProperties(SessionId sessionId,
                                          Collection<String> requiredProperties,
                                          C context,
                                          ClientControl.SessionPropertiesContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Query the server for property values of a specified client session.
    
    Type Parameters:
    
    C - the context object type
    
    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.
    
    context - passed to the callback to allow requests and responses to be correlated. The caller can use any convenient object reference, including null
    
    callback - called with the response
    
    Since:
    
    5.6
  - 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:
    
    NoSuchSessionException – if the identified session was closed before the response was delivered;
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permission;
    SessionClosedException – if the calling session is closed.
    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:
    
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permission;
    SessionClosedException – if the calling session is closed.
    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:
    
    SessionClosedException – if the session is closed;
    HandlerConflictException – if the session has already registered a queue event handler;
    PermissionsException – if the session does not have REGISTER_HANDLER permission;
    PermissionsException – if the session does not have VIEW_SESSION permission.
    Since:
    
    6.0
  - setQueueEventHandler
```
@Deprecated
void setQueueEventHandler(ClientControl.QueueEventHandler handler)
```
    Deprecated. since 6.7
    The CompletableFuture-based alternative setQueueEventHandler(QueueEventStream) should be preferred since it provides better error reporting.
    
    Register a handler for client queue threshold events.
    Each control session can register a single handler. (See ServerHandler.onActive(RegisteredHandler)). A handler may be closed (using 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.
    
    Parameters:
    
    handler - the queue handler to set
  - 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:
    
    NoSuchSessionException – if the identified session was closed before the response was delivered;
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permissions;
    SessionClosedException – if the calling session is closed.
    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:
    
    InvalidFilterException – if the filter was invalid;
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permissions;
    SessionClosedException – if the calling session is closed.
    Since:
    
    6.5
  - close
```
@Deprecated
void close(SessionId sessionId,
                       ClientControl.ClientCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Close a client session.
    The CompletableFuture-based alternative close(SessionId) should be preferred since it provides better error reporting.
    
    Parameters:
    
    sessionId - identifies the client session to close
    
    callback - the operation callback
    
    Since:
    
    5.5
  - close
```
@Deprecated
<C> void close(SessionId sessionId,
                           C context,
                           ClientControl.ClientContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Close a client session with a contextual callback.
    The CompletableFuture-based alternative close(SessionId) should be preferred since it provides better error reporting.
    
    Type Parameters:
    
    C - the context type
    
    Parameters:
    
    sessionId - identifies the client session to close
    
    context - the context object to pass to the callback
    
    callback - the operation callback
    
    Since:
    
    5.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:
    
    NoSuchSessionException – if the identified session was closed before the response was delivered;
    PermissionsException – if the calling session does not have MODIFY_SESSION and {code VIEW_SESSION} permissions;
    SessionClosedException – if the calling session is closed.
    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:
    
    InvalidFilterException – if the filter parameter could not be parsed;
    PermissionsException – if the calling session does not have MODIFY_SESSION or VIEW_SESSION permissions;
    SessionClosedException – if the calling session is closed.
    Since:
    
    6.5
  - setConflated
```
@Deprecated
void setConflated(SessionId sessionId,
                              boolean conflate,
                              ClientControl.ClientCallback callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    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.
    The CompletableFuture-based alternative setConflated(SessionId, boolean) should be preferred since it provides better error reporting.
    
    Parameters:
    
    sessionId - identifies the client session
    
    conflate - true to enable conflation, false to disable conflation
    
    callback - the operation callback
  - setConflated
```
@Deprecated
<C> void setConflated(SessionId sessionId,
                                  boolean conflate,
                                  C context,
                                  ClientControl.ClientContextCallback<C> callback)
```
    Deprecated. since 6.7
    Methods that use callbacks are deprecated and will be removed in a future release. Use CompletableFuture variant instead.
    
    Control client queue conflation with a contextual callback.
    The CompletableFuture-based alternative setConflated(SessionId, boolean) should be preferred since it provides better error reporting.
    
    Type Parameters:
    
    C - the context type
    
    Parameters:
    
    sessionId - identifies the client session
    
    conflate - true to enable conflation, false to disable conflation
    
    context - the context to pass to the callback
    
    callback - the operation callback
  - sessionIdFromString
```
@Deprecated
SessionId sessionIdFromString(String sessionIdAsString)
                                   throws IllegalArgumentException
```
    Deprecated. since 6.7
    Use Diffusion.sessionIdFromString(java.lang.String) which allows the method to be statically imported. This method will be removed in a future release.
    
    Restore a SessionId from a string.
    This method allows a SessionId to be converted to a string with SessionId.toString() and later recovered from the string. This is a client operation. A session that has been closed will not be recreated.
    
    Parameters:
    
    sessionIdAsString - a string, previously created with SessionId.toString()
    
    Returns:
    
    the SessionId
    
    Throws:
    
    IllegalArgumentException - if the string was not generated by SessionId.toString()
    
    Since:
    
    5.2
  - 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:
    
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permission;
    NoSuchSessionException – if there is no session with the given sessionId;
    SessionClosedException – if the calling session is closed.
    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:
    
    PermissionsException – if the calling session does not have MODIFY_SESSION and VIEW_SESSION permissions;
    SessionClosedException – if the calling session is closed.
    InvalidFilterException – if the filter parameter could not be parsed;
    Throws:
    
    IllegalArgumentException - if the same role occurs in both rolesToRemove and rolesToAdd sets or if both sets are empty
    
    Since:
    
    6.2

Interface ClientControl

Access control

Accessing the feature

Nested Class Summary

Method Summary

Methods inherited from interface com.pushtechnology.diffusion.client.session.Feature

Method Detail

addSessionEventListener

setSessionPropertiesListener

getSessionProperties

getSessionProperties

getSessionProperties

setSessionProperties

setSessionProperties

setQueueEventHandler

setQueueEventHandler

close

close

close

close

setConflated

setConflated

setConflated

setConflated

sessionIdFromString

changeRoles

changeRoles