public interface ClientControl extends Feature
It allows for notifications of client sessions starting and closing as well as the ability to manage client sessions (forcibly closing them etc).
VIEW_SESSION
permission to be able to listen for notifications using
setSessionDetailsListener(Set, SessionDetailsListener)
or
setSessionPropertiesListener(SessionPropertiesListener, String...)
,
get
details
or
get properties
of other sessions or listen for
queue events
. In addition
REGISTER_HANDLER
permission is
required to set a session properties listener, a session details listener or
queue event handler.
In order to perform operations that change another session's state (such as
throttling, conflating or closing), both
VIEW_SESSION
and
MODIFY_SESSION
permission is
required.
session
as follows:
ClientControl clientControl = session.feature(ClientControl.class);
Modifier and Type | Interface and Description |
---|---|
static interface |
ClientControl.ClientCallback
|
static interface |
ClientControl.ClientContextCallback<C>
|
static class |
ClientControl.CloseReason
The server's view of why a client session was closed.
|
static interface |
ClientControl.QueueEventHandler
Handler for client queue events.
|
static interface |
ClientControl.SessionDetailsCallback
The callback interface for
getSessionDetails . |
static interface |
ClientControl.SessionDetailsContextCallback<C>
Contextual callback interface for
getSessionDetails . |
static interface |
ClientControl.SessionDetailsListener
The listener for notifications of session details.
|
static interface |
ClientControl.SessionPropertiesCallback
The callback interface for
getSessionProperties(SessionId, Collection, SessionPropertiesCallback)
. |
static interface |
ClientControl.SessionPropertiesContextCallback<C>
Contextual callback interface for
getSessionProperties(SessionId, Collection, Object, SessionPropertiesContextCallback)
. |
static interface |
ClientControl.SessionPropertiesListener
The handler for session properties listener notifications.
|
Modifier and Type | Method and Description |
---|---|
<C> void |
close(SessionId sessionId,
C context,
ClientControl.ClientContextCallback<C> callback)
Close a client session with a contextual callback.
|
void |
close(SessionId sessionId,
ClientControl.ClientCallback callback)
Close a client session.
|
<C> void |
close(SessionId sessionId,
String reason,
C context,
ClientControl.ClientContextCallback<C> callback)
Deprecated.
since 5.5. The reason parameter is not passed to the client
session being closed. Prefer
close(SessionId sessionId, ClientCallback callback)
instead.
If you want to notify the client being closed of the reason
for its closure, use the MessagingControl feature to send a
message to the client. To ensure that this message is
received before closing the client session, wait for the
callback to return before calling
close(SessionId sessionId, ClientCallback callback) |
void |
close(SessionId sessionId,
String reason,
ClientControl.ClientCallback callback)
Deprecated.
since 5.5. The reason parameter is not passed to the client
session being closed. Prefer
close(SessionId sessionId, ClientCallback callback)
instead.
If you want to notify the client being closed of the reason
for its closure, use the MessagingControl feature to send a
message to the client. To ensure that this message is
received before closing the client session, wait for the
callback to return before calling
close(SessionId sessionId, ClientCallback callback) |
<C> void |
getSessionDetails(SessionId sessionId,
Set<SessionDetails.DetailType> types,
C context,
ClientControl.SessionDetailsContextCallback<C> callback)
Deprecated.
since 5.6 the use of
getSessionProperties(SessionId, Collection, Object, SessionPropertiesContextCallback)
is preferred and this method will be removed at a future
release |
void |
getSessionDetails(SessionId sessionId,
Set<SessionDetails.DetailType> types,
ClientControl.SessionDetailsCallback callback)
Deprecated.
since 5.6 the use of
getSessionProperties(SessionId, Collection, SessionPropertiesCallback)
is preferred and this method will be removed at a future
release |
<C> void |
getSessionProperties(SessionId sessionId,
Collection<String> requiredProperties,
C context,
ClientControl.SessionPropertiesContextCallback<C> callback)
Query the server for property values of a specified client session.
|
void |
getSessionProperties(SessionId sessionId,
Collection<String> requiredProperties,
ClientControl.SessionPropertiesCallback callback)
Query the server for property values of a specified client session.
|
SessionId |
sessionIdFromString(String sessionIdAsString)
Restore a
SessionId from a string. |
<C> void |
setConflated(SessionId sessionId,
boolean conflate,
C context,
ClientControl.ClientContextCallback<C> callback)
Control client queue conflation with a contextual callback.
|
void |
setConflated(SessionId sessionId,
boolean conflate,
ClientControl.ClientCallback callback)
Control client queue conflation.
|
void |
setQueueEventHandler(ClientControl.QueueEventHandler handler)
Register a handler for client queue threshold events.
|
void |
setSessionDetailsListener(Set<SessionDetails.DetailType> requiredDetail,
ClientControl.SessionDetailsListener listener)
Deprecated.
since 5.6 the use of
setSessionPropertiesListener(SessionPropertiesListener, String...)
is preferred and this method will be removed at a future
release |
void |
setSessionPropertiesListener(ClientControl.SessionPropertiesListener listener,
String... requiredProperties)
Register a listener that will be notified when client sessions are
opened, disconnected, reconnected, closed or when selected session
property values are updated.
|
<C> void |
setThrottled(SessionId sessionId,
MessageQueuePolicy.ThrottlerType throttlerType,
int throttlingLimit,
C context,
ClientControl.ClientContextCallback<C> callback)
Instruct a client session to conflate its message queue, and to throttle
the queue according to the provided parameters.
|
void |
setThrottled(SessionId sessionId,
MessageQueuePolicy.ThrottlerType throttlerType,
int throttlingLimit,
ClientControl.ClientCallback callback)
Instruct a client session to conflate its message queue, and to throttle
the queue according to the provided parameters.
|
getSession
void setSessionPropertiesListener(ClientControl.SessionPropertiesListener listener, String... requiredProperties) throws IllegalArgumentException, SessionClosedException
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 (See
ServerHandler.onRegistered(Registration)
). A listener
may be closed (using Registration.close()
) if no longer required.
To set a different listener the current 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.
listener
- the listener to be called with session notificationsrequiredProperties
- 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.IllegalArgumentException
- if listener
is nullSessionClosedException
- if the current session is closedvoid getSessionProperties(SessionId sessionId, Collection<String> requiredProperties, ClientControl.SessionPropertiesCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client sessionrequiredProperties
- 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 responseSessionClosedException
- if the local session is closedIllegalArgumentException
- if sessionId
, callback
or requiredProperties
is null<C> void getSessionProperties(SessionId sessionId, Collection<String> requiredProperties, C context, ClientControl.SessionPropertiesContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- the context object typesessionId
- identifies the client sessionrequiredProperties
- 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 responseSessionClosedException
- if the local session is closedIllegalArgumentException
- if sessionId
, callback
or requiredProperties
is null@Deprecated void setSessionDetailsListener(Set<SessionDetails.DetailType> requiredDetail, ClientControl.SessionDetailsListener listener) throws IllegalArgumentException, SessionClosedException
setSessionPropertiesListener(SessionPropertiesListener, String...)
is preferred and this method will be removed at a future
release
When a listener is first set, it will be called with the details 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
requiredDetail
parameter,
Each control session can register a single listener (See
ServerHandler.onActive(RegisteredHandler)
). A listener
may be closed (using RegisteredHandler.close()
) if no longer
required. To set a different listener the current listener must first be
closed.
The requiredDetail
set is usually an EnumSet
.
For example, EnumSet.allOf(DetailType.class)
can be used to
request all session details. The set controls the level of detail
provided and whether the listener is called for updates to sessions. The
listener is always called when sessions are opened or closed. The set may
be empty, in which case the listener is only called when sessions are
opened or closed
requiredDetail
- specifies the level of detail provided to the
listener , and determines whether
onSessionUpdate
will be calledlistener
- the listener to registerIllegalArgumentException
- if requiredDetail
or
listener
is nullSessionClosedException
- if the local session is closed@Deprecated void getSessionDetails(SessionId sessionId, Set<SessionDetails.DetailType> types, ClientControl.SessionDetailsCallback callback) throws IllegalArgumentException, SessionClosedException
getSessionProperties(SessionId, Collection, SessionPropertiesCallback)
is preferred and this method will be removed at a future
releasesessionId
- identifies the client sessiontypes
- a list of the types of detail to returncallback
- called with the responseSessionClosedException
- if the local session is closedIllegalArgumentException
- if any of sessionId
,
types
or callback
is null@Deprecated <C> void getSessionDetails(SessionId sessionId, Set<SessionDetails.DetailType> types, C context, ClientControl.SessionDetailsContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
getSessionProperties(SessionId, Collection, Object, SessionPropertiesContextCallback)
is preferred and this method will be removed at a future
releaseC
- the context object typesessionId
- identifies the client sessiontypes
- a list of the types of detail to returncontext
- passed to the callback to allow requests and responses to
be correlated. The caller may use any convenient object reference,
including null
callback
- called with the responseSessionClosedException
- if the local session is closedIllegalArgumentException
- if any of sessionId
,
types
or callback
is nullvoid setQueueEventHandler(ClientControl.QueueEventHandler handler) throws IllegalArgumentException, SessionClosedException
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 client may choose to act upon client queue events by conflating or throttling the client.
handler
- the queue handler to setIllegalArgumentException
- if handler
is nullSessionClosedException
- if the session is closed@Deprecated void close(SessionId sessionId, String reason, ClientControl.ClientCallback callback) throws IllegalArgumentException, SessionClosedException
close(SessionId sessionId, ClientCallback callback)
instead.
If you want to notify the client being closed of the reason
for its closure, use the MessagingControl feature to send a
message to the client. To ensure that this message is
received before closing the client session, wait for the
callback to return before calling
close(SessionId sessionId, ClientCallback callback)
sessionId
- identifies the client session to closereason
- unusedcallback
- the operation callbackIllegalArgumentException
- if sessionId
or reason
is nullSessionClosedException
- if the local session is closedvoid close(SessionId sessionId, ClientControl.ClientCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client session to closecallback
- the operation callbackIllegalArgumentException
- if sessionId
or reason
is nullSessionClosedException
- if the local session is closed@Deprecated <C> void close(SessionId sessionId, String reason, C context, ClientControl.ClientContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
close(SessionId sessionId, ClientCallback callback)
instead.
If you want to notify the client being closed of the reason
for its closure, use the MessagingControl feature to send a
message to the client. To ensure that this message is
received before closing the client session, wait for the
callback to return before calling
close(SessionId sessionId, ClientCallback callback)
C
- the context typesessionId
- identifies the client session to closereason
- unusedcontext
- the context object to pass to the callbackcallback
- the operation callbackIllegalArgumentException
- if sessionId
or reason
is nullSessionClosedException
- if the local session is closed.<C> void close(SessionId sessionId, C context, ClientControl.ClientContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- the context typesessionId
- identifies the client session to closecontext
- the context object to pass to the callbackcallback
- the operation callbackIllegalArgumentException
- if sessionId
or reason
is nullSessionClosedException
- if the local session is closed.void setConflated(SessionId sessionId, boolean conflate, ClientControl.ClientCallback callback) throws IllegalArgumentException, SessionClosedException
Calling this method will also disable throttling. Use
setThrottled
to enable both conflation and throttling.
sessionId
- identifies the client sessionconflate
- true
to enable conflation, false
to
disable conflationcallback
- the operation callbackIllegalArgumentException
- if sessionId
is nullSessionClosedException
- if the local session is closed<C> void setConflated(SessionId sessionId, boolean conflate, C context, ClientControl.ClientContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
Calling this method will also disable throttling. Use
setThrottled
to enable both conflation and throttling.
C
- the context typesessionId
- identifies the client sessionconflate
- true
to enable conflation, false
to
disable conflationcontext
- the context to pass to the callbackcallback
- the operation callbackIllegalArgumentException
- if sessionId
is nullSessionClosedException
- if the local session is closedvoid setThrottled(SessionId sessionId, MessageQueuePolicy.ThrottlerType throttlerType, int throttlingLimit, ClientControl.ClientCallback callback) throws IllegalArgumentException, SessionClosedException
sessionId
- identifies the client sessionthrottlerType
- the type of throttlingthrottlingLimit
- The throttling limit. The meaning of this limit
depends upon the throttlerType
callback
- the operation callbackIllegalArgumentException
- if sessionId
or
throttlerType
is nullSessionClosedException
- if the local session is closed<C> void setThrottled(SessionId sessionId, MessageQueuePolicy.ThrottlerType throttlerType, int throttlingLimit, C context, ClientControl.ClientContextCallback<C> callback) throws IllegalArgumentException, SessionClosedException
C
- the context typesessionId
- identifies the client sessionthrottlerType
- the type of throttlingthrottlingLimit
- The throttling limit. The meaning of this limit
depends upon the throttlerType
context
- the context to pass to the callbackcallback
- the operation callbackIllegalArgumentException
- if sessionId
or
throttlerType
is nullSessionClosedException
- if the local session is closedSessionId sessionIdFromString(String sessionIdAsString)
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.
sessionIdAsString
- a string, previously created with
SessionId.toString()
SessionId
IllegalArgumentException
- if the string was not generated by
SessionId.toString()
Copyright © 2016 Push Technology Ltd. All Rights Reserved.