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

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

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

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