All Superinterfaces:

AutoCloseable, Closeable
```
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(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.

Author:

dannycoward

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`addMessageHandler(MessageHandler handler)`	Register to handle to incoming messages in this conversation.
`<T> void`	`addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)`	Register to handle to incoming messages in this conversation.
`<T> void`	`addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> 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.
`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.
`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.
`URI`	`getRequestURI()`	Return the complete URI under which this session was opened, from protocol to query string (if present).
`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.
`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.

- Method Detail
  - 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.
    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.
    
    Parameters:
    
    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.
  - addMessageHandler
```
<T> void addMessageHandler(Class<T> clazz,
                           MessageHandler.Whole<T> handler)
```
    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.
    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.
    
    Type Parameters:
    
    T - type of message that the given handler is intended for.
    
    Parameters:
    
    clazz - type of the message processed by message handler to be registered.
    
    handler - whole message handler to be added.
    
    Throws:
    
    IllegalStateException - if there is already a MessageHandler registered for the same native websocket message type as this handler.
    
    Since:
    
    WebSocket 1.1
  - addMessageHandler
```
<T> void addMessageHandler(Class<T> clazz,
                           MessageHandler.Partial<T> handler)
```
    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.
    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.
    
    Type Parameters:
    
    T - type of message that the given handler is intended for.
    
    Parameters:
    
    clazz - type of the message processed by message handler to be registered.
    
    handler - partial message handler to be added.
    
    Throws:
    
    IllegalStateException - if there is already a MessageHandler registered for the same native websocket message type as this handler.
    
    Since:
    
    WebSocket 1.1
  - 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.
    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.
    
    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.
  - isOpen
```
boolean isOpen()
```
    Return true if and only if the underlying socket is open.
    
    Returns:
    
    whether the session is active.
  - getMaxIdleTimeout
```
long getMaxIdleTimeout()
```
    Return the number of milliseconds before this session will be closed by the container if it is inactive, i.e. no messages are either sent or received in that time. A value that is zero or negative indicates that this timeout will not be used.
    
    Returns:
    
    the timeout in milliseconds.
  - setMaxIdleTimeout
```
void setMaxIdleTimeout(long milliseconds)
```
    Set the number of milliseconds before this session will be closed by the container if it is inactive, i.e. no messages are either sent or received in that time. A value that is zero or negative indicates that this timeout will not be used.
    
    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.
    
    Returns:
    
    the maximum binary message size that can be buffered.
  - 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.
    
    Returns:
    
    the maximum text message size that can be buffered.
  - 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.
  - close
```
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.
  - close
```
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.
    
    Parameters:
    
    closeReason - the reason for the closure.
    
    Throws:
    
    IOException - if there was a connection error closing the connection
  - getRequestURI
```
URI getRequestURI()
```
    Return the complete URI under which this session was opened, from protocol to query string (if present). The URI should be identical to the complete URI used for the HTTP request that was upgraded to WebSocket apart from the protocol which should be changed to 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.
    
    Returns:
    
    the request URI.
  - getRequestParameterMap
```
Map<String,List<String>> getRequestParameterMap()
```
    Return the request parameters associated with the request this session was opened under. The request parameters will have been part of the HTTP upgrade request which is limited by RFC 6455 to only use the HTTP GET method. Therefore, the parameters in the returned Map will be a representation of the parameters contained in the query string.
    
    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.
    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).
    
    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.

Interface Session

Method Summary

Method Detail

getContainer

addMessageHandler

addMessageHandler

addMessageHandler

getMessageHandlers

removeMessageHandler

getProtocolVersion

getNegotiatedSubprotocol

getNegotiatedExtensions

isSecure

isOpen

getMaxIdleTimeout

setMaxIdleTimeout

setMaxBinaryMessageBufferSize

getMaxBinaryMessageBufferSize

setMaxTextMessageBufferSize

getMaxTextMessageBufferSize

getAsyncRemote

getBasicRemote

getId

close

close

getRequestURI

getRequestParameterMap

getQueryString

getPathParameters

getUserProperties

getUserPrincipal

getOpenSessions