# Interface Session

All Superinterfaces:
  `AutoCloseable, Closeable`

public interface Session extends Closeable
Represents a WebSocket session, which is the WebSocket connection between a client and a server. A session is created when a WebSocket connection is established and is used to send and receive messages.

## Method Summary

Modifier and Type
Method
Description
`void`
`addMessageHandler(MessageHandler handler)`
Registers a `MessageHandler` for incoming messages.
`<T> void`
`addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)`
Registers a `MessageHandler` for partial incoming messages.
`<T> void`
`addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler)`
Registers a `MessageHandler` for whole incoming messages.
`void`
`close()`
Close the connection to the remote end point using the code `CloseReason.CloseCodes.NORMAL_CLOSURE` and an empty reason phrase.
`void`
`close(CloseReason closeReason)`
Close the connection to the remote end point using the specified code and reason phrase.
`RemoteEndpoint.Async`
`getAsyncRemote()`
Returns the asynchronous remote endpoint for this session, used for non-blocking message sending.
`RemoteEndpoint.Basic`
`getBasicRemote()`
Returns the synchronous remote endpoint for this session, used for blocking message sending.
`WebSocketContainer`
`getContainer()`
Get the container that created this session.
`String`
`getId()`
Provides a unique identifier for the session.
`int`
`getMaxBinaryMessageBufferSize()`
Get the current maximum buffer size for binary messages.
`long`
`getMaxIdleTimeout()`
Get the idle timeout for this session.
`int`
`getMaxTextMessageBufferSize()`
Get the maximum buffer size for text messages.
`Set<MessageHandler>`
`getMessageHandlers()`
Returns the set of message handlers currently registered on this session.
`List<Extension>`
`getNegotiatedExtensions()`
Returns the list of extensions negotiated for this session.
`String`
`getNegotiatedSubprotocol()`
Returns the sub-protocol negotiated for this session, or `null` if no sub-protocol was negotiated.
`Set<Session>`
`getOpenSessions()`
Obtain the set of open sessions associated with the same local endpoint as this session.
`Map<String,String>`
`getPathParameters()`
Returns the path parameters extracted from the request URI using the endpoint's URI template.
`String`
`getProtocolVersion()`
Returns the version of the WebSocket protocol in use for this session.
`String`
`getQueryString()`
Returns the query string from the request that initiated this WebSocket session.
`Map<String, List<String>>`
`getRequestParameterMap()`
Returns the query parameters from the request that initiated this WebSocket session.
`URI`
`getRequestURI()`
Returns the URI of the request that initiated this WebSocket session.
`Principal`
`getUserPrincipal()`
Returns the principal of the user associated with this session, or `null` if the user is not authenticated.
`Map<String,Object>`
`getUserProperties()`
Returns a map of user properties associated with this session.
`boolean`
`isOpen()`
Returns whether this session is currently open.
`boolean`
`isSecure()`
Returns whether this session is using a secure connection (wss://).
`void`
`removeMessageHandler(MessageHandler listener)`
Removes the specified message handler from this session.
`void`
`setMaxBinaryMessageBufferSize(int max)`
Set the current maximum buffer size for binary messages.
`void`
`setMaxIdleTimeout(long timeout)`
Set the idle timeout for this session.
`void`
`setMaxTextMessageBufferSize(int max)`
Set the maximum buffer size for text messages.

## Method Details

### getContainer

WebSocketContainer getContainer()
Get the container that created this session.

Returns:
  the container that created this session.

### addMessageHandler

void addMessageHandler(MessageHandler handler) throws IllegalStateException
Registers a `MessageHandler` for incoming messages. Only one `MessageHandler` may be registered for each message type (text, binary, pong). The message type will be derived at runtime from the provided `MessageHandler` instance. It is not always possible to do this so it is better to use `addMessageHandler(Class, jakarta.websocket.MessageHandler.Partial)` or `addMessageHandler(Class, jakarta.websocket.MessageHandler.Whole)`.

Parameters:
  `handler` - The message handler for a incoming message
Throws:
  `IllegalStateException` - If a message handler has already been registered for the associated message type

### getMessageHandlers

Set<MessageHandler> getMessageHandlers()
Returns the set of message handlers currently registered on this session.

Returns:
  The set of registered message handlers

### removeMessageHandler

void removeMessageHandler(MessageHandler listener)
Removes the specified message handler from this session.

Parameters:
  `listener` - The message handler to remove

### getProtocolVersion

String getProtocolVersion()
Returns the version of the WebSocket protocol in use for this session.

Returns:
  The protocol version

### getNegotiatedSubprotocol

String getNegotiatedSubprotocol()
Returns the sub-protocol negotiated for this session, or `null` if no sub-protocol was negotiated.

Returns:
  The negotiated sub-protocol

### getNegotiatedExtensions

List<Extension> getNegotiatedExtensions()
Returns the list of extensions negotiated for this session.

Returns:
  The list of negotiated extensions

### isSecure

boolean isSecure()
Returns whether this session is using a secure connection (wss://).

Returns:
  `true` if the connection is secure

### isOpen

boolean isOpen()
Returns whether this session is currently open.

Returns:
  `true` if the session is open

### getMaxIdleTimeout

long getMaxIdleTimeout()
Get the idle timeout for this session.

Returns:
  The current idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

### setMaxIdleTimeout

void setMaxIdleTimeout(long timeout)
Set the idle timeout for this session.

Parameters:
  `timeout` - The new idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

### setMaxBinaryMessageBufferSize

void setMaxBinaryMessageBufferSize(int max)
Set the current maximum buffer size for binary messages.

Parameters:
  `max` - The new maximum buffer size in bytes

### getMaxBinaryMessageBufferSize

int getMaxBinaryMessageBufferSize()
Get the current maximum buffer size for binary messages.

Returns:
  The current maximum buffer size in bytes

### setMaxTextMessageBufferSize

void setMaxTextMessageBufferSize(int max)
Set the maximum buffer size for text messages.

Parameters:
  `max` - The new maximum buffer size in characters.

### getMaxTextMessageBufferSize

int getMaxTextMessageBufferSize()
Get the maximum buffer size for text messages.

Returns:
  The maximum buffer size in characters.

### getAsyncRemote

RemoteEndpoint.Async getAsyncRemote()
Returns the asynchronous remote endpoint for this session, used for non-blocking message sending.

Returns:
  The asynchronous remote endpoint

### getBasicRemote

RemoteEndpoint.Basic getBasicRemote()
Returns the synchronous remote endpoint for this session, used for blocking message sending.

Returns:
  The synchronous remote endpoint

### getId

String getId()
Provides a unique identifier for the session. This identifier should not be relied upon to be generated from a secure random source.

Returns:
  A unique identifier for the session.

### close

void close() throws IOException
Close the connection to the remote end point using the code `CloseReason.CloseCodes.NORMAL_CLOSURE` and an empty reason phrase.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `IOException` - if an I/O error occurs while the WebSocket session is being closed.

### close

void close(CloseReason closeReason) throws IOException
Close the connection to the remote end point using the specified code and reason phrase.

Parameters:
  `closeReason` - The reason the WebSocket session is being closed.
Throws:
  `IOException` - if an I/O error occurs while the WebSocket session is being closed.

### getRequestURI

URI getRequestURI()
Returns the URI of the request that initiated this WebSocket session.

Returns:
  The request URI

### getRequestParameterMap

Map<String, List<String>> getRequestParameterMap()
Returns the query parameters from the request that initiated this WebSocket session.

Returns:
  The query parameter map

### getQueryString

String getQueryString()
Returns the query string from the request that initiated this WebSocket session.

Returns:
  The query string

### getPathParameters

Map<String,String> getPathParameters()
Returns the path parameters extracted from the request URI using the endpoint's URI template.

Returns:
  The path parameter map

### getUserProperties

Map<String,Object> getUserProperties()
Returns a map of user properties associated with this session.

Returns:
  The user properties map

### getUserPrincipal

Principal getUserPrincipal()
Returns the principal of the user associated with this session, or `null` if the user is not authenticated.

Returns:
  The user principal

### getOpenSessions

Set<Session> getOpenSessions()
Obtain the set of open sessions associated with the same local endpoint as this session.

Returns:
  The set of currently open sessions for the local endpoint that this session is associated with.

### addMessageHandler

<T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) throws IllegalStateException
Registers a `MessageHandler` for partial incoming messages. Only one `MessageHandler` may be registered for each message type (text or binary, pong messages are never presented as partial messages).

Type Parameters:
  `T` - The type of message that the given handler is intended for
Parameters:
  `clazz` - The Class that implements T
  `handler` - The message handler for a incoming message
Throws:
  `IllegalStateException` - If a message handler has already been registered for the associated message type
Since:
  WebSocket 1.1

### addMessageHandler

<T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) throws IllegalStateException
Registers a `MessageHandler` for whole incoming messages. Only one `MessageHandler` may be registered for each message type (text, binary, pong).

Type Parameters:
  `T` - The type of message that the given handler is intended for
Parameters:
  `clazz` - The Class that implements T
  `handler` - The message handler for a incoming message
Throws:
  `IllegalStateException` - If a message handler has already been registered for the associated message type
Since:
  WebSocket 1.1