Session (WebSocket 2.2 API Documentation - Apache Tomcat 11.0.25)
Description: declaration: package: jakarta.websocket, interface: Session

# 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 an 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 an 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 an incoming message
    Throws:
      `IllegalStateException` - If a message handler has already been registered for the associated message type
    Since:
      WebSocket 1.1