Session (WebSocket 2.0 API Documentation - Apache Tomcat 10.0.20)

Package jakarta.websocket

## Interface Session

- All Superinterfaces:
    `java.lang.AutoCloseable`, `java.io.Closeable`

      public interface Session
      extends java.io.Closeable

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addMessageHandler​(MessageHandler handler)` | Registers a `MessageHandler` for incoming messages.
    `<T> void` | `addMessageHandler​(java.lang.Class<T> clazz, MessageHandler.Partial<T> handler)` | Registers a `MessageHandler` for partial incoming messages.
    `<T> void` | `addMessageHandler​(java.lang.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()` |
    `RemoteEndpoint.Basic` | `getBasicRemote()` |
    `WebSocketContainer` | `getContainer()` | Get the container that created this session.
    `java.lang.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.
    `java.util.Set<MessageHandler>` | `getMessageHandlers()` |
    `java.util.List<Extension>` | `getNegotiatedExtensions()` |
    `java.lang.String` | `getNegotiatedSubprotocol()` |
    `java.util.Set<Session>` | `getOpenSessions()` | Obtain the set of open sessions associated with the same local endpoint as this session.
    `java.util.Map<java.lang.String,​java.lang.String>` | `getPathParameters()` |
    `java.lang.String` | `getProtocolVersion()` |
    `java.lang.String` | `getQueryString()` |
    `java.util.Map<java.lang.String,​java.util.List<java.lang.String>>` | `getRequestParameterMap()` |
    `java.net.URI` | `getRequestURI()` |
    `java.security.Principal` | `getUserPrincipal()` |
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getUserProperties()` |
    `boolean` | `isOpen()` |
    `boolean` | `isSecure()` |
    `void` | `removeMessageHandler​(MessageHandler listener)` |
    `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 Detail

    - #### getContainer

          WebSocketContainer getContainer()

      Get the container that created this session.
      Returns:
        the container that created this session.

    - #### addMessageHandler

          void addMessageHandler​(MessageHandler handler)
                          throws java.lang.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:
        `java.lang.IllegalStateException` - If a message handler has already been registered for the associated message type

    - #### getMessageHandlers

          java.util.Set<MessageHandler> getMessageHandlers()

    - #### removeMessageHandler

          void removeMessageHandler​(MessageHandler listener)

    - #### getProtocolVersion

          java.lang.String getProtocolVersion()

    - #### getNegotiatedSubprotocol

          java.lang.String getNegotiatedSubprotocol()

    - #### getNegotiatedExtensions

          java.util.List<Extension> getNegotiatedExtensions()

    - #### isSecure

          boolean isSecure()

    - #### isOpen

          boolean isOpen()

    - #### 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()

    - #### getBasicRemote

          RemoteEndpoint.Basic getBasicRemote()

    - #### getId

          java.lang.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 java.io.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 `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Throws:
        `java.io.IOException` - if an I/O error occurs while the WebSocket session is being closed.

    - #### close

          void close​(CloseReason closeReason)
              throws java.io.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:
        `java.io.IOException` - if an I/O error occurs while the WebSocket session is being closed.

    - #### getRequestURI

          java.net.URI getRequestURI()

    - #### getRequestParameterMap

          java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getRequestParameterMap()

    - #### getQueryString

          java.lang.String getQueryString()

    - #### getPathParameters

          java.util.Map<java.lang.String,​java.lang.String> getPathParameters()

    - #### getUserProperties

          java.util.Map<java.lang.String,​java.lang.Object> getUserProperties()

    - #### getUserPrincipal

          java.security.Principal getUserPrincipal()

    - #### getOpenSessions

          java.util.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​(java.lang.Class<T> clazz,
                                     MessageHandler.Partial<T> handler)
                              throws java.lang.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:
        `java.lang.IllegalStateException` - If a message handler has already been registered for the associated message type
      Since:
        WebSocket 1.1

    - #### addMessageHandler

          <T> void addMessageHandler​(java.lang.Class<T> clazz,
                                     MessageHandler.Whole<T> handler)
                              throws java.lang.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:
        `java.lang.IllegalStateException` - If a message handler has already been registered for the associated message type
      Since:
        WebSocket 1.1