WsSession (Apache Tomcat 10.1.57 API Documentation)
Description: declaration: package: org.apache.tomcat.websocket, class: WsSession

# Class WsSession

java.lang.Object
org.apache.tomcat.websocket.WsSession

All Implemented Interfaces:
  `Session, Closeable, AutoCloseable`

public class WsSession extends Object implements Session
Implementation of a WebSocket session.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `WsSession(ClientEndpointHolder clientEndpointHolder, WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, List<Extension> negotiatedExtensions, String subProtocol, Map<String,String> pathParameters, boolean secure, ClientEndpointConfig clientEndpointConfig)`
  Creates a new WebSocket session for communication between the provided client and remote end points.
  `WsSession(WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, URI requestUri, Map<String, List<String>> requestParameterMap, String queryString, Principal userPrincipal, String httpSessionId, List<Extension> negotiatedExtensions, String subProtocol, Map<String,String> pathParameters, boolean secure, ServerEndpointConfig serverEndpointConfig)`
  Creates a new WebSocket session for communication between the provided server and remote end points.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addMessageHandler(MessageHandler listener)`
  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.
  `protected static void`
  `appendCloseReasonWithTruncation(ByteBuffer msg, String reason)`
  Use protected so unit tests can access this method directly.
  `protected void`
  `checkCloseTimeout()`
  Checks if the session close timeout has expired and closes the connection if so.
  `protected void`
  `checkExpiration()`
  Checks if this session has expired based on idle timeout settings.
  `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.
  `void`
  `doClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal)`
  WebSocket 1.0.
  `void`
  `doClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal, boolean closeSocket)`
  WebSocket 1.0.
  `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.
  `protected MessageHandler`
  `getBinaryMessageHandler()`
  Returns the binary message handler for this session.
  `WebSocketContainer`
  `getContainer()`
  Get the container that created this session.
  `String`
  `getHttpSessionId()`
  Returns the HTTP session ID associated with this WebSocket session.
  `String`
  `getId()`
  Provides a unique identifier for the session.
  `InstanceManager`
  `getInstanceManager()`
  Returns the instance manager for this session.
  `Endpoint`
  `getLocal()`
  Returns the local endpoint for this 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.
  `protected MessageHandler.Whole<PongMessage>`
  `getPongMessageHandler()`
  Returns the pong message handler for this session.
  `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.
  `protected long`
  `getSessionCloseTimeout()`
  Returns the session close timeout in milliseconds.
  `protected MessageHandler`
  `getTextMessageHandler()`
  Returns the text message handler for this session.
  `Principal`
  `getUserPrincipal()`
  Returns the principal of the user associated with this session, or `null` if the user is not authenticated.
  `Principal`
  `getUserPrincipalInternal()`
  Returns the user principal for this session.
  `Map<String,Object>`
  `getUserProperties()`
  Returns a map of user properties associated with this session.
  `boolean`
  `isClosed()`
  Checks if the session is closed.
  `boolean`
  `isOpen()`
  Returns whether this session is currently open.
  `boolean`
  `isSecure()`
  Returns whether this session is using a secure connection (wss://).
  `void`
  `onClose(CloseReason closeReason)`
  Called when a close message is received.
  `void`
  `removeMessageHandler(MessageHandler listener)`
  Removes the specified message handler from this session.
  `void`
  `resume()`
  Resumes the reading of the incoming messages.
  `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.
  `void`
  `suspend()`
  Suspends the reading of the incoming messages.
  `protected void`
  `updateLastActiveRead()`
  Updates the last active read timestamp to the current time.
  `protected void`
  `updateLastActiveWrite()`
  Updates the last active write timestamp to the current time.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### WsSession

    public WsSession(ClientEndpointHolder clientEndpointHolder, WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, List<Extension> negotiatedExtensions, String subProtocol, Map<String,String> pathParameters, boolean secure, ClientEndpointConfig clientEndpointConfig) throws DeploymentException
    Creates a new WebSocket session for communication between the provided client and remote end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
    Parameters:
      `clientEndpointHolder` - The end point managed by this code
      `wsRemoteEndpoint` - The other / remote end point
      `wsWebSocketContainer` - The container that created this session
      `negotiatedExtensions` - The agreed extensions to use for this session
      `subProtocol` - The agreed sub-protocol to use for this session
      `pathParameters` - The path parameters associated with the request that initiated this session or `null` if this is a client session
      `secure` - Was this session initiated over a secure connection?
      `clientEndpointConfig` - The configuration information for the client end point
    Throws:
      `DeploymentException` - if an invalid encode is specified

  - ### WsSession

    public WsSession(WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, URI requestUri, Map<String, List<String>> requestParameterMap, String queryString, Principal userPrincipal, String httpSessionId, List<Extension> negotiatedExtensions, String subProtocol, Map<String,String> pathParameters, boolean secure, ServerEndpointConfig serverEndpointConfig) throws DeploymentException
    Creates a new WebSocket session for communication between the provided server and remote end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
    Parameters:
      `wsRemoteEndpoint` - The other / remote end point
      `wsWebSocketContainer` - The container that created this session
      `requestUri` - The URI used to connect to this end point or `null` if this is a client session
      `requestParameterMap` - The parameters associated with the request that initiated this session or `null` if this is a client session
      `queryString` - The query string associated with the request that initiated this session or `null` if this is a client session
      `userPrincipal` - The principal associated with the request that initiated this session or `null` if this is a client session
      `httpSessionId` - The HTTP session ID associated with the request that initiated this session or `null` if this is a client session
      `negotiatedExtensions` - The agreed extensions to use for this session
      `subProtocol` - The agreed sub-protocol to use for this session
      `pathParameters` - The path parameters associated with the request that initiated this session or `null` if this is a client session
      `secure` - Was this session initiated over a secure connection?
      `serverEndpointConfig` - The configuration information for the server end point
    Throws:
      `DeploymentException` - if an invalid encode is specified

- ## Method Details

  - ### getInstanceManager

    public InstanceManager getInstanceManager()
    Returns the instance manager for this session.
    Returns:
      the instance manager

  - ### getContainer

    public WebSocketContainer getContainer()
    Description copied from interface: `jakarta.websocket.Session`
    Get the container that created this session.
    Specified by:
      `getContainer` in interface `Session`
    Returns:
      the container that created this session.

  - ### addMessageHandler

    public void addMessageHandler(MessageHandler listener)
    Description copied from interface: `jakarta.websocket.Session`
    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 `Session.addMessageHandler(Class, jakarta.websocket.MessageHandler.Partial)` or `Session.addMessageHandler(Class, jakarta.websocket.MessageHandler.Whole)`.
    Specified by:
      `addMessageHandler` in interface `Session`
    Parameters:
      `listener` - The message handler for a incoming message

  - ### addMessageHandler

    public <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) throws IllegalStateException
    Description copied from interface: `jakarta.websocket.Session`
    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).
    Specified by:
      `addMessageHandler` in interface `Session`
    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

  - ### addMessageHandler

    public <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) throws IllegalStateException
    Description copied from interface: `jakarta.websocket.Session`
    Registers a `MessageHandler` for whole incoming messages. Only one `MessageHandler` may be registered for each message type (text, binary, pong).
    Specified by:
      `addMessageHandler` in interface `Session`
    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

  - ### getMessageHandlers

    public Set<MessageHandler> getMessageHandlers()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the set of message handlers currently registered on this session.
    Specified by:
      `getMessageHandlers` in interface `Session`
    Returns:
      The set of registered message handlers

  - ### removeMessageHandler

    public void removeMessageHandler(MessageHandler listener)
    Description copied from interface: `jakarta.websocket.Session`
    Removes the specified message handler from this session.
    Specified by:
      `removeMessageHandler` in interface `Session`
    Parameters:
      `listener` - The message handler to remove

  - ### getProtocolVersion

    public String getProtocolVersion()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the version of the WebSocket protocol in use for this session.
    Specified by:
      `getProtocolVersion` in interface `Session`
    Returns:
      The protocol version

  - ### getNegotiatedSubprotocol

    public String getNegotiatedSubprotocol()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the sub-protocol negotiated for this session, or `null` if no sub-protocol was negotiated.
    Specified by:
      `getNegotiatedSubprotocol` in interface `Session`
    Returns:
      The negotiated sub-protocol

  - ### getNegotiatedExtensions

    public List<Extension> getNegotiatedExtensions()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the list of extensions negotiated for this session.
    Specified by:
      `getNegotiatedExtensions` in interface `Session`
    Returns:
      The list of negotiated extensions

  - ### isSecure

    public boolean isSecure()
    Description copied from interface: `jakarta.websocket.Session`
    Returns whether this session is using a secure connection (wss://).
    Specified by:
      `isSecure` in interface `Session`
    Returns:
      `true` if the connection is secure

  - ### isOpen

    public boolean isOpen()
    Description copied from interface: `jakarta.websocket.Session`
    Returns whether this session is currently open.
    Specified by:
      `isOpen` in interface `Session`
    Returns:
      `true` if the session is open

  - ### isClosed

    public boolean isClosed()
    Checks if the session is closed.
    Returns:
      true if the session is closed

  - ### getMaxIdleTimeout

    public long getMaxIdleTimeout()
    Description copied from interface: `jakarta.websocket.Session`
    Get the idle timeout for this session.
    Specified by:
      `getMaxIdleTimeout` in interface `Session`
    Returns:
      The current idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

  - ### setMaxIdleTimeout

    public void setMaxIdleTimeout(long timeout)
    Description copied from interface: `jakarta.websocket.Session`
    Set the idle timeout for this session.
    Specified by:
      `setMaxIdleTimeout` in interface `Session`
    Parameters:
      `timeout` - The new idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

  - ### setMaxBinaryMessageBufferSize

    public void setMaxBinaryMessageBufferSize(int max)
    Description copied from interface: `jakarta.websocket.Session`
    Set the current maximum buffer size for binary messages.
    Specified by:
      `setMaxBinaryMessageBufferSize` in interface `Session`
    Parameters:
      `max` - The new maximum buffer size in bytes

  - ### getMaxBinaryMessageBufferSize

    public int getMaxBinaryMessageBufferSize()
    Description copied from interface: `jakarta.websocket.Session`
    Get the current maximum buffer size for binary messages.
    Specified by:
      `getMaxBinaryMessageBufferSize` in interface `Session`
    Returns:
      The current maximum buffer size in bytes

  - ### setMaxTextMessageBufferSize

    public void setMaxTextMessageBufferSize(int max)
    Description copied from interface: `jakarta.websocket.Session`
    Set the maximum buffer size for text messages.
    Specified by:
      `setMaxTextMessageBufferSize` in interface `Session`
    Parameters:
      `max` - The new maximum buffer size in characters.

  - ### getMaxTextMessageBufferSize

    public int getMaxTextMessageBufferSize()
    Description copied from interface: `jakarta.websocket.Session`
    Get the maximum buffer size for text messages.
    Specified by:
      `getMaxTextMessageBufferSize` in interface `Session`
    Returns:
      The maximum buffer size in characters.

  - ### getOpenSessions

    public Set<Session> getOpenSessions()
    Description copied from interface: `jakarta.websocket.Session`
    Obtain the set of open sessions associated with the same local endpoint as this session.
    Specified by:
      `getOpenSessions` in interface `Session`
    Returns:
      The set of currently open sessions for the local endpoint that this session is associated with.

  - ### getAsyncRemote

    public RemoteEndpoint.Async getAsyncRemote()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the asynchronous remote endpoint for this session, used for non-blocking message sending.
    Specified by:
      `getAsyncRemote` in interface `Session`
    Returns:
      The asynchronous remote endpoint

  - ### getBasicRemote

    public RemoteEndpoint.Basic getBasicRemote()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the synchronous remote endpoint for this session, used for blocking message sending.
    Specified by:
      `getBasicRemote` in interface `Session`
    Returns:
      The synchronous remote endpoint

  - ### close

    public void close() throws IOException
    Description copied from interface: `jakarta.websocket.Session`
    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`
    Specified by:
      `close` in interface `Session`
    Throws:
      `IOException` - if an I/O error occurs while the WebSocket session is being closed.

  - ### close

    public void close(CloseReason closeReason) throws IOException
    Description copied from interface: `jakarta.websocket.Session`
    Close the connection to the remote end point using the specified code and reason phrase.
    Specified by:
      `close` in interface `Session`
    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.

  - ### doClose

    public void doClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal)
    WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006 on timeout.
    Parameters:
      `closeReasonMessage` - The close reason to pass to the remote endpoint
      `closeReasonLocal` - The close reason to pass to the local endpoint

  - ### doClose

    public void doClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal, boolean closeSocket)
    WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006 on timeout.
    Parameters:
      `closeReasonMessage` - The close reason to pass to the remote endpoint
      `closeReasonLocal` - The close reason to pass to the local endpoint
      `closeSocket` - Should the socket be closed immediately rather than waiting for the server to respond

  - ### onClose

    public void onClose(CloseReason closeReason)
    Called when a close message is received. Should only ever happen once. Also called after a protocol error when the ProtocolHandler needs to force the closing of the connection.
    Parameters:
      `closeReason` - The reason contained within the received close message.

  - ### getSessionCloseTimeout

    protected long getSessionCloseTimeout()
    Returns the session close timeout in milliseconds.
    Returns:
      the session close timeout

  - ### checkCloseTimeout

    protected void checkCloseTimeout()
    Checks if the session close timeout has expired and closes the connection if so.

  - ### appendCloseReasonWithTruncation

    protected static void appendCloseReasonWithTruncation(ByteBuffer msg, String reason)
    Use protected so unit tests can access this method directly.
    Parameters:
      `msg` - The message
      `reason` - The reason

  - ### getRequestURI

    public URI getRequestURI()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the URI of the request that initiated this WebSocket session.
    Specified by:
      `getRequestURI` in interface `Session`
    Returns:
      The request URI

  - ### getRequestParameterMap

    public Map<String, List<String>> getRequestParameterMap()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the query parameters from the request that initiated this WebSocket session.
    Specified by:
      `getRequestParameterMap` in interface `Session`
    Returns:
      The query parameter map

  - ### getQueryString

    public String getQueryString()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the query string from the request that initiated this WebSocket session.
    Specified by:
      `getQueryString` in interface `Session`
    Returns:
      The query string

  - ### getUserPrincipal

    public Principal getUserPrincipal()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the principal of the user associated with this session, or `null` if the user is not authenticated.
    Specified by:
      `getUserPrincipal` in interface `Session`
    Returns:
      The user principal

  - ### getUserPrincipalInternal

    public Principal getUserPrincipalInternal()
    Returns the user principal for this session.
    Returns:
      the user principal

  - ### getPathParameters

    public Map<String,String> getPathParameters()
    Description copied from interface: `jakarta.websocket.Session`
    Returns the path parameters extracted from the request URI using the endpoint's URI template.
    Specified by:
      `getPathParameters` in interface `Session`
    Returns:
      The path parameter map

  - ### getId

    public String getId()
    Description copied from interface: `jakarta.websocket.Session`
    Provides a unique identifier for the session. This identifier should not be relied upon to be generated from a secure random source.
    Specified by:
      `getId` in interface `Session`
    Returns:
      A unique identifier for the session.

  - ### getUserProperties

    public Map<String,Object> getUserProperties()
    Description copied from interface: `jakarta.websocket.Session`
    Returns a map of user properties associated with this session.
    Specified by:
      `getUserProperties` in interface `Session`
    Returns:
      The user properties map

  - ### getLocal

    public Endpoint getLocal()
    Returns the local endpoint for this session.
    Returns:
      the local endpoint

  - ### getHttpSessionId

    public String getHttpSessionId()
    Returns the HTTP session ID associated with this WebSocket session.
    Returns:
      the HTTP session ID, or null if not associated

  - ### getTextMessageHandler

    protected MessageHandler getTextMessageHandler()
    Returns the text message handler for this session.
    Returns:
      the text message handler

  - ### getBinaryMessageHandler

    protected MessageHandler getBinaryMessageHandler()
    Returns the binary message handler for this session.
    Returns:
      the binary message handler

  - ### getPongMessageHandler

    protected MessageHandler.Whole<PongMessage> getPongMessageHandler()
    Returns the pong message handler for this session.
    Returns:
      the pong message handler

  - ### updateLastActiveRead

    protected void updateLastActiveRead()
    Updates the last active read timestamp to the current time.

  - ### updateLastActiveWrite

    protected void updateLastActiveWrite()
    Updates the last active write timestamp to the current time.

  - ### checkExpiration

    protected void checkExpiration()
    Checks if this session has expired based on idle timeout settings.

  - ### suspend

    public void suspend()
    Suspends the reading of the incoming messages.

  - ### resume

    public void resume()
    Resumes the reading of the incoming messages.