public interface Session
extends Closeable
A Web Socket session represents a conversation between two web socket endpoints. As soon
as the websocket handshake completes successfully, the web socket implementation provides
the endpoint an open websocket session. The endpoint can then register interest in incoming
messages that are part of this newly created session by providing a MessageHandler to the
session, and can send messages to the other end of the conversation by means of the RemoteEndpoint object
obtained from this session.
Once the session is closed, it is no longer valid for use by applications. Calling any of
its methods (with the exception of the close() methods)
once the session has been closed will result in an
IllegalStateException
being thrown.
Developers should retrieve any information from the session during the
Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason)
method. Following the convention of
Closeable
calling the Session close() methods after the Session has been closed has no
effect.
Session objects may be called by multiple threads. Implementations must
ensure the integrity of the mutable properties of the session under such circumstances.
RemoteEndpoint.Async
getAsyncRemote
()
Return a reference a RemoteEndpoint object representing the peer of this conversation
that is able to send messages asynchronously to the peer.
RemoteEndpoint.Basic
getBasicRemote
()
Return a reference a RemoteEndpoint object representing the peer of this conversation
that is able to send messages synchronously to the peer.
WebSocketContainer
getContainer
()
Return the container that this session is part of.
String
getId
()
Returns a string containing the unique identifier assigned to this session.
getMaxBinaryMessageBufferSize
()
The maximum length of incoming binary messages that this Session can buffer.
getMaxIdleTimeout
()
Return the number of milliseconds before this conversation may be closed by the
container if it is inactive, i.e.
getMaxTextMessageBufferSize
()
The maximum length of incoming text messages that this Session can buffer.
Set
<
MessageHandler
>
getMessageHandlers
()
Return an unmodifiable copy of the set of MessageHandlers for this Session.
List
<
Extension
>
getNegotiatedExtensions
()
Return the list of extensions currently in use for this conversation.
String
getNegotiatedSubprotocol
()
Return the sub protocol agreed during the websocket handshake for this conversation.
Set
<
Session
>
getOpenSessions
()
Return a copy of the Set of all the open web socket sessions that represent
connections to the same endpoint to which this session represents a connection.
Map
<
String
,
String
>
getPathParameters
()
Return a map of the path parameter names and values used associated with the
request this session was opened under.
String
getProtocolVersion
()
Returns the version of the websocket protocol currently being used.
String
getQueryString
()
Return the query string associated with the request this session
was opened under.
Map
<
String
,
List
<
String
>>
getRequestParameterMap
()
Return the request parameters associated with the request this session
was opened under.
getRequestURI
()
Return the URI under which this session was opened, including
the query string if there is one.
Principal
getUserPrincipal
()
Return the authenticated user for this Session or
null
if no user is authenticated for this session.
Map
<
String
,
Object
>
getUserProperties
()
While the session is open, this method returns a Map that the developer may
use to store application specific information relating to this session
instance.
boolean
isOpen
()
Return true if and only if the underlying socket is open.
boolean
isSecure
()
Return true if and only if the underlying socket is using a secure transport.
removeMessageHandler
(
MessageHandler
handler)
Remove the given MessageHandler from the set belonging to this session.
setMaxBinaryMessageBufferSize
(int length)
Sets the maximum length of incoming binary messages that this Session can buffer.
setMaxIdleTimeout
(long milliseconds)
Set the non-zero number of milliseconds before this session will be closed by the
container if it is inactive, ie no messages are either sent or received.
setMaxTextMessageBufferSize
(int length)
Sets the maximum length of incoming text messages that this Session can buffer.
getContainer
WebSocketContainer getContainer()
Return the container that this session is part of.
Returns:
the container.
addMessageHandler
void addMessageHandler(MessageHandler handler)
throws IllegalStateException
Register to handle to incoming messages in this conversation. A maximum of one message handler per
native websocket message type (text, binary, pong) may be added to each Session. I.e. a maximum
of one message handler to handle incoming text messages a maximum of one message handler for
handling incoming binary messages, and a maximum of one for handling incoming pong
messages. For further details of which message handlers handle which of the native websocket
message types please see
MessageHandler.Whole
and
MessageHandler.Partial
.
Adding more than one of any one type will result in a runtime exception.
See
Endpoint
for a usage example.
handler
- the MessageHandler to be added.
Throws:
IllegalStateException
- if there is already a MessageHandler registered for the same native
websocket message type as this handler.
getMessageHandlers
Set<MessageHandler> getMessageHandlers()
Return an unmodifiable copy of the set of MessageHandlers for this Session.
Returns:
the set of message handlers.
removeMessageHandler
void removeMessageHandler(MessageHandler handler)
Remove the given MessageHandler from the set belonging to this session. This method may block
if the given handler is processing a message until it is no longer in use.
Parameters:
handler
- the handler to be removed.
getProtocolVersion
String getProtocolVersion()
Returns the version of the websocket protocol currently being used. This is taken
as the value of the Sec-WebSocket-Version header used in the opening handshake. i.e. "13".
Returns:
the protocol version.
getNegotiatedSubprotocol
String getNegotiatedSubprotocol()
Return the sub protocol agreed during the websocket handshake for this conversation.
Returns:
the negotiated subprotocol, or the empty string if there isn't one.
getNegotiatedExtensions
List<Extension> getNegotiatedExtensions()
Return the list of extensions currently in use for this conversation.
Returns:
the negotiated extensions.
isSecure
boolean isSecure()
Return true if and only if the underlying socket is using a secure transport.
Returns:
whether its using a secure transport.
getMaxIdleTimeout
long getMaxIdleTimeout()
Return the number of milliseconds before this conversation may be closed by the
container if it is inactive, i.e. no messages are either sent or received in that time.
Returns:
the timeout in milliseconds.
setMaxIdleTimeout
void setMaxIdleTimeout(long milliseconds)
Set the non-zero number of milliseconds before this session will be closed by the
container if it is inactive, ie no messages are either sent or received. A value that is
0 or negative indicates the session will never timeout due to inactivity.
Parameters:
milliseconds
- the number of milliseconds.
setMaxBinaryMessageBufferSize
void setMaxBinaryMessageBufferSize(int length)
Sets the maximum length of incoming binary messages that this Session can buffer.
Parameters:
length
- the maximum length.
getMaxBinaryMessageBufferSize
int getMaxBinaryMessageBufferSize()
The maximum length of incoming binary messages that this Session can buffer. If
the implementation receives a binary message that it cannot buffer because it
is too large, it must close the session with a close code of
CloseReason.CloseCodes.TOO_BIG
.
setMaxTextMessageBufferSize
void setMaxTextMessageBufferSize(int length)
Sets the maximum length of incoming text messages that this Session can buffer.
Parameters:
length
- the maximum length.
getMaxTextMessageBufferSize
int getMaxTextMessageBufferSize()
The maximum length of incoming text messages that this Session can buffer. If
the implementation receives a text message that it cannot buffer because it
is too large, it must close the session with a close code of
CloseReason.CloseCodes.TOO_BIG
.
getAsyncRemote
RemoteEndpoint.Async getAsyncRemote()
Return a reference a RemoteEndpoint object representing the peer of this conversation
that is able to send messages asynchronously to the peer.
Returns:
the remote endpoint.
getBasicRemote
RemoteEndpoint.Basic getBasicRemote()
Return a reference a RemoteEndpoint object representing the peer of this conversation
that is able to send messages synchronously to the peer.
Returns:
the remote endpoint.
getId
String getId()
Returns a string containing the unique identifier assigned to this session.
The identifier is assigned by the web socket implementation and is implementation dependent.
Returns:
the unique identifier for this session instance.
void close()
throws IOException
Close the current conversation with a normal status code and no reason phrase.
Specified by:
close
in interface
AutoCloseable
Specified by:
close
in interface
Closeable
Throws:
IOException
- if there was a connection error closing the connection.
void close(CloseReason closeReason)
throws IOException
Close the current conversation, giving a reason for the closure. The close
call causes the implementation to attempt notify the client of the close as
soon as it can. This may cause the sending of unsent messages immediately
prior to the close notification. After the close notification has been sent
the implementation notifies the endpoint's onClose method. Note the websocket
specification defines the
acceptable uses of status codes and reason phrases. If the application cannot
determine a suitable close code to use for the closeReason, it is recommended
to use
CloseReason.CloseCodes.NO_STATUS_CODE
.
closeReason
- the reason for the closure.
Throws:
IOException
- if there was a connection error closing the connection
getRequestURI
URI getRequestURI()
Return the URI under which this session was opened, including
the query string if there is one.
Returns:
the request URI.
getRequestParameterMap
Map<String,List<String>> getRequestParameterMap()
Return the request parameters associated with the request this session
was opened under.
Returns:
the unmodifiable map of the request parameters.
getQueryString
String getQueryString()
Return the query string associated with the request this session
was opened under.
Returns:
the query string
getPathParameters
Map<String,String> getPathParameters()
Return a map of the path parameter names and values used associated with the
request this session was opened under.
Returns:
the unmodifiable map of path parameters. The key of the map is the parameter name,
the values in the map are the parameter values.
getUserProperties
Map<String,Object> getUserProperties()
While the session is open, this method returns a Map that the developer may
use to store application specific information relating to this session
instance. The developer may retrieve information from this Map at any time
between the opening of the session and during the onClose() method. But outside
that time, any information stored using this Map may no longer be kept by the
container. Web socket applications running on distributed implementations of
the web container should make any application specific objects stored here
java.io.Serializable, or the object may not be recreated after a failover.
Returns:
an editable Map of application data.
getUserPrincipal
Principal getUserPrincipal()
Return the authenticated user for this Session or
null
if no user is authenticated for this session.
Returns:
the user principal.
getOpenSessions
Set<Session> getOpenSessions()
Return a copy of the Set of all the open web socket sessions that represent
connections to the same endpoint to which this session represents a connection.
The Set includes the session this method is called on. These
sessions may not still be open at any point after the return of this method. For
example, iterating over the set at a later time may yield one or more closed sessions. Developers
should use session.isOpen() to check.
Returns:
the set of sessions, open at the time of return.
