WsSession (Apache Tomcat 9.0.37 API Documentation)

org.apache.tomcat.websocket

## 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 and 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)` Creates a new WebSocket session for communication between the two provided end points.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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` | `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.
    `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 MessageHandler` | `getTextMessageHandler()`
    `Principal` | `getUserPrincipal()`
    `Map<String,Object>` | `getUserProperties()`
    `boolean` | `isOpen()`
    `boolean` | `isSecure()`
    `void` | `onClose(CloseReason closeReason)` Called when a close message is received.
    `protected void` | `registerFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh)` Make the session aware of a `FutureToSendHandler` that will need to be forcibly closed if the session closes before the `FutureToSendHandler` completes.
    `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` | `unregisterFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh)` Remove a `FutureToSendHandler` from the set of tracked instances.
    `protected void` | `updateLastActive()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### WsSession

          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

      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 Detail

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

    - #### 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 `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      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.

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

    - #### registerFuture

          protected void registerFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh)

      Make the session aware of a `FutureToSendHandler` that will need to be forcibly closed if the session closes before the `FutureToSendHandler` completes.
      Parameters:
        `f2sh` - The handler

    - #### unregisterFuture

          protected void unregisterFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh)

      Remove a `FutureToSendHandler` from the set of tracked instances.
      Parameters:
        `f2sh` - The handler

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

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

    - #### updateLastActive

          protected void updateLastActive()

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

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.