public interface Session
extends java.io.Closeable
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(jakarta.websocket.Session, jakarta.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.
Modifier and Type | Method and Description |
---|---|
<T> void |
addMessageHandler(java.lang.Class<T> clazz,
MessageHandler.Partial<T> handler)
Register to handle to incoming messages in this conversation.
|
<T> void |
addMessageHandler(java.lang.Class<T> clazz,
MessageHandler.Whole<T> handler)
Register to handle to incoming messages in this conversation.
|
void |
addMessageHandler(MessageHandler handler)
Register to handle to incoming messages in this conversation.
|
void |
close()
Close the current conversation with a normal status code and no reason phrase.
|
void |
close(CloseReason closeReason)
Close the current conversation, giving a reason for the closure.
|
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.
|
java.lang.String |
getId()
Returns a string containing the unique identifier assigned to this session.
|
int |
getMaxBinaryMessageBufferSize()
The maximum length of incoming binary messages that this Session can buffer.
|
long |
getMaxIdleTimeout()
Return the number of milliseconds before this session will be closed by the container if it is inactive, i.e.
|
int |
getMaxTextMessageBufferSize()
The maximum length of incoming text messages that this Session can buffer.
|
java.util.Set<MessageHandler> |
getMessageHandlers()
Return an unmodifiable copy of the set of MessageHandlers for this Session.
|
java.util.List<Extension> |
getNegotiatedExtensions()
Return the list of extensions currently in use for this conversation.
|
java.lang.String |
getNegotiatedSubprotocol()
Return the sub protocol agreed during the websocket handshake for this conversation.
|
java.util.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.
|
java.util.Map<java.lang.String,java.lang.String> |
getPathParameters()
Return a map of the path parameter names and values used associated with the request this session was opened
under.
|
java.lang.String |
getProtocolVersion()
Returns the version of the websocket protocol currently being used.
|
java.lang.String |
getQueryString()
Return the query string associated with the request this session was opened under.
|
java.util.Map<java.lang.String,java.util.List<java.lang.String>> |
getRequestParameterMap()
Return the request parameters associated with the request this session was opened under.
|
java.net.URI |
getRequestURI()
Return the complete URI under which this session was opened, from protocol to query string (if present).
|
java.security.Principal |
getUserPrincipal()
Return the authenticated user for this Session or
null if no user is authenticated for this session. |
java.util.Map<java.lang.String,java.lang.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.
|
void |
removeMessageHandler(MessageHandler handler)
Remove the given MessageHandler from the set belonging to this session.
|
void |
setMaxBinaryMessageBufferSize(int length)
Sets the maximum length of incoming binary messages that this Session can buffer.
|
void |
setMaxIdleTimeout(long milliseconds)
Set the number of milliseconds before this session will be closed by the container if it is inactive, i.e.
|
void |
setMaxTextMessageBufferSize(int length)
Sets the maximum length of incoming text messages that this Session can buffer.
|
WebSocketContainer getContainer()
void addMessageHandler(MessageHandler handler) throws java.lang.IllegalStateException
MessageHandler.Whole
and MessageHandler.Partial
.
Adding more than one of any one type will result in a runtime exception.
This method is not safe to use unless you are providing an anonymous class derived directly from
MessageHandler.Whole
or MessageHandler.Partial
. In all other
cases (Lambda Expressions, more complex inheritance or generic type arrangements), one of the following methods
have to be used: addMessageHandler(Class, jakarta.websocket.MessageHandler.Whole)
or
addMessageHandler(Class, jakarta.websocket.MessageHandler.Partial)
.
Once the container has identified a MessageHandler for a message, the MessageHandler is used for the entirety of the message irrespective of any subsequent changes to the MessageHandlers configured for the Session.
handler
- the MessageHandler to be added.java.lang.IllegalStateException
- if there is already a MessageHandler registered for the same native websocket
message type as this handler.<T> void addMessageHandler(java.lang.Class<T> clazz, MessageHandler.Whole<T> handler)
MessageHandler.Whole
and MessageHandler.Partial
.
Adding more than one of any one type will result in a runtime exception.
Once the container has identified a MessageHandler for a message, the MessageHandler is used for the entirety of the message irrespective of any subsequent changes to the MessageHandlers configured for the Session.
T
- type of message that the given handler is intended for.clazz
- type of the message processed by message handler to be registered.handler
- whole message handler to be added.java.lang.IllegalStateException
- if there is already a MessageHandler registered for the same native websocket
message type as this handler.<T> void addMessageHandler(java.lang.Class<T> clazz, MessageHandler.Partial<T> handler)
MessageHandler.Whole
and MessageHandler.Partial
.
Adding more than one of any one type will result in a runtime exception.
Once the container has identified a MessageHandler for a message, the MessageHandler is used for the entirety of the message irrespective of any subsequent changes to the MessageHandlers configured for the Session.
T
- type of message that the given handler is intended for.clazz
- type of the message processed by message handler to be registered.handler
- partial message handler to be added.java.lang.IllegalStateException
- if there is already a MessageHandler registered for the same native websocket
message type as this handler.java.util.Set<MessageHandler> getMessageHandlers()
void removeMessageHandler(MessageHandler handler)
Once the container has identified a MessageHandler for a message, the MessageHandler is used for the entirety of the message irrespective of any subsequent changes to the MessageHandlers configured for the Session.
handler
- the handler to be removed.java.lang.String getProtocolVersion()
java.lang.String getNegotiatedSubprotocol()
java.util.List<Extension> getNegotiatedExtensions()
boolean isSecure()
boolean isOpen()
long getMaxIdleTimeout()
void setMaxIdleTimeout(long milliseconds)
milliseconds
- the number of milliseconds.void setMaxBinaryMessageBufferSize(int length)
length
- the maximum length.int getMaxBinaryMessageBufferSize()
CloseReason.CloseCodes.TOO_BIG
.void setMaxTextMessageBufferSize(int length)
length
- the maximum length.int getMaxTextMessageBufferSize()
CloseReason.CloseCodes.TOO_BIG
.RemoteEndpoint.Async getAsyncRemote()
RemoteEndpoint.Basic getBasicRemote()
java.lang.String getId()
void close() throws java.io.IOException
close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
java.io.IOException
- if there was a connection error closing the connection.void close(CloseReason closeReason) throws java.io.IOException
CloseReason.CloseCodes.NO_STATUS_CODE
.closeReason
- the reason for the closure.java.io.IOException
- if there was a connection error closing the connectionjava.net.URI getRequestURI()
ws
or wss
as appropriate. It is the URI associated with the
HTTP request that received the 101 Switching Protocols
response that is used as the basis for this value
- not an earlier, redirected request - if any.java.util.Map<java.lang.String,java.util.List<java.lang.String>> getRequestParameterMap()
java.lang.String getQueryString()
java.util.Map<java.lang.String,java.lang.String> getPathParameters()
java.util.Map<java.lang.String,java.lang.Object> getUserProperties()
For server sessions, the initial contents of this Map must be a shallow copy of the user properties map returned
from jakarta.websocket.server.ServerEndpointConfig#getUserProperties()
at the point the
jakarta.websocket.server.ServerEndpointConfig.Configurator#modifyHandshake()
method exits.
For client sessions, the initial contents of this Map must be a shallow copy of the user properties map returned
from EndpointConfig.getUserProperties()
for the ClientEndpointConfig
passed to
WebSocketContainer.connectToServer(Class, ClientEndpointConfig, URI)
or
WebSocketContainer.connectToServer(Endpoint, ClientEndpointConfig, URI)
.
java.security.Principal getUserPrincipal()
null
if no user is authenticated for this session.java.util.Set<Session> getOpenSessions()