WsSession (Apache Tomcat 11.0.25 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()`
  Deprecated.
  Unused.
  `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 an 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 an 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 an 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

    @Deprecated public String getHttpSessionId()
    Deprecated.
    Unused. Will be removed from Tomcat 12 onwards
    Returns the HTTP session ID associated with this WebSocket session at the time the WebSocket session was created.
    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.