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

# Class WsSession

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

All Implemented Interfaces:
  `Closeable, AutoCloseable, Session`

public class WsSession extends Object implements Session

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `WsSession(Endpoint localEndpoint, 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, EndpointConfig endpointConfig)`
  Deprecated.
  Unused.
  `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
  `<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`
  `addMessageHandler(MessageHandler listener)`
  Registers a `MessageHandler` for incoming messages.
  `protected static void`
  `appendCloseReasonWithTruncation(ByteBuffer msg, String reason)`
  Use protected so unit tests can access this method directly.
  `protected void`
  `checkCloseTimeout()`
  `protected void`
  `checkExpiration()`
  `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()`
  `RemoteEndpoint.Basic`
  `getBasicRemote()`
  `protected MessageHandler`
  `getBinaryMessageHandler()`
  `WebSocketContainer`
  `getContainer()`
  Get the container that created this session.
  `String`
  `getHttpSessionId()`
  `String`
  `getId()`
  Provides a unique identifier for the session.
  `InstanceManager`
  `getInstanceManager()`
  `Endpoint`
  `getLocal()`
  `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()`
  `List<Extension>`
  `getNegotiatedExtensions()`
  `String`
  `getNegotiatedSubprotocol()`
  `Set<Session>`
  `getOpenSessions()`
  Obtain the set of open sessions associated with the same local endpoint as this session.
  `Map<String,String>`
  `getPathParameters()`
  `protected MessageHandler.Whole<PongMessage>`
  `getPongMessageHandler()`
  `String`
  `getProtocolVersion()`
  `String`
  `getQueryString()`
  `Map<String, List<String>>`
  `getRequestParameterMap()`
  `URI`
  `getRequestURI()`
  `protected long`
  `getSessionCloseTimeout()`
  `protected MessageHandler`
  `getTextMessageHandler()`
  `Principal`
  `getUserPrincipal()`
  `Principal`
  `getUserPrincipalInternal()`
  `Map<String,Object>`
  `getUserProperties()`
  `boolean`
  `isClosed()`
  `boolean`
  `isOpen()`
  `boolean`
  `isSecure()`
  `void`
  `onClose(CloseReason closeReason)`
  Called when a close message is received.
  `void`
  `removeMessageHandler(MessageHandler listener)`
  `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()`
  `protected void`
  `updateLastActiveWrite()`

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

  - ### WsSession

    @Deprecated public WsSession(Endpoint localEndpoint, 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, EndpointConfig endpointConfig) throws DeploymentException
    Deprecated.
    Unused. This will be removed in Tomcat 10.1
    Creates a new WebSocket session for communication between the two provided end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
    Parameters:
      `localEndpoint` - The end point managed by this code
      `wsRemoteEndpoint` - The other / remote endpoint
      `wsWebSocketContainer` - The container that created this session
      `requestUri` - The URI used to connect to this endpoint or `null` is 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 subprotocol 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?
      `endpointConfig` - The configuration information for the endpoint
    Throws:
      `DeploymentException` - if an invalid encode is specified

- ## Method Details

  - ### getInstanceManager

    public InstanceManager getInstanceManager()

  - ### getContainer

    public WebSocketContainer getContainer()
    Description copied from interface: `javax.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: `javax.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, javax.websocket.MessageHandler.Partial)` or `Session.addMessageHandler(Class, javax.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: `javax.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: `javax.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()
    Specified by:
      `getMessageHandlers` in interface `Session`

  - ### removeMessageHandler

    public void removeMessageHandler(MessageHandler listener)
    Specified by:
      `removeMessageHandler` in interface `Session`

  - ### getProtocolVersion

    public String getProtocolVersion()
    Specified by:
      `getProtocolVersion` in interface `Session`

  - ### getNegotiatedSubprotocol

    public String getNegotiatedSubprotocol()
    Specified by:
      `getNegotiatedSubprotocol` in interface `Session`

  - ### getNegotiatedExtensions

    public List<Extension> getNegotiatedExtensions()
    Specified by:
      `getNegotiatedExtensions` in interface `Session`

  - ### isSecure

    public boolean isSecure()
    Specified by:
      `isSecure` in interface `Session`

  - ### isOpen

    public boolean isOpen()
    Specified by:
      `isOpen` in interface `Session`

  - ### isClosed

    public boolean isClosed()

  - ### getMaxIdleTimeout

    public long getMaxIdleTimeout()
    Description copied from interface: `javax.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: `javax.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: `javax.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: `javax.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: `javax.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: `javax.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: `javax.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()
    Specified by:
      `getAsyncRemote` in interface `Session`

  - ### getBasicRemote

    public RemoteEndpoint.Basic getBasicRemote()
    Specified by:
      `getBasicRemote` in interface `Session`

  - ### close

    public void close() throws IOException
    Description copied from interface: `javax.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: `javax.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()

  - ### checkCloseTimeout

    protected void checkCloseTimeout()

  - ### 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()
    Specified by:
      `getRequestURI` in interface `Session`

  - ### getRequestParameterMap

    public Map<String, List<String>> getRequestParameterMap()
    Specified by:
      `getRequestParameterMap` in interface `Session`

  - ### getQueryString

    public String getQueryString()
    Specified by:
      `getQueryString` in interface `Session`

  - ### getUserPrincipal

    public Principal getUserPrincipal()
    Specified by:
      `getUserPrincipal` in interface `Session`

  - ### getUserPrincipalInternal

    public Principal getUserPrincipalInternal()

  - ### getPathParameters

    public Map<String,String> getPathParameters()
    Specified by:
      `getPathParameters` in interface `Session`

  - ### getId

    public String getId()
    Description copied from interface: `javax.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()
    Specified by:
      `getUserProperties` in interface `Session`

  - ### getLocal

    public Endpoint getLocal()

  - ### getHttpSessionId

    public String getHttpSessionId()

  - ### getTextMessageHandler

    protected MessageHandler getTextMessageHandler()

  - ### getBinaryMessageHandler

    protected MessageHandler getBinaryMessageHandler()

  - ### getPongMessageHandler

    protected MessageHandler.Whole<PongMessage> getPongMessageHandler()

  - ### updateLastActiveRead

    protected void updateLastActiveRead()

  - ### updateLastActiveWrite

    protected void updateLastActiveWrite()

  - ### checkExpiration

    protected void checkExpiration()

  - ### suspend

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

  - ### resume

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