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

Methods
`void` `addMessageHandler(MessageHandler listener)`
`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.
`RemoteEndpoint.Async` `getAsyncRemote()`
`RemoteEndpoint.Basic` `getBasicRemote()`
`protected MessageHandler` `getBinaryMessageHandler()`
`WebSocketContainer` `getContainer()` Returns 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 (in bytes) for binary messages.
`long` `getMaxIdleTimeout()` Get the idle timeout for this session in milliseconds.
`int` `getMaxTextMessageBufferSize()` Get the current maximum buffer size (in characters) for text messages.
`Set<MessageHandler>` `getMessageHandlers()`
`List<Extension>` `getNegotiatedExtensions()`
`String` `getNegotiatedSubprotocol()`
`Set<Session>` `getOpenSessions()` Obtain the set of currently open sessions for the local endpoint that this session is associated with.
`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` `setMaxBinaryMessageBufferSize(int max)` Set the current maximum buffer size (in bytes) for binary messages.
`void` `setMaxIdleTimeout(long timeout)` Set the idle timeout for this session in milliseconds.
`void` `setMaxTextMessageBufferSize(int max)` Set the current maximum buffer size (in characters) for text 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,
             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` -
  `wsRemoteEndpoint` -
Throws:
  `DeploymentException`

### Method Detail

#### getContainer

    public WebSocketContainer getContainer()

Description copied from interface: `javax.websocket.Session`
Returns the container that created this session.

Specified by:
  `getContainer` in interface `Session`

#### addMessageHandler

    public void addMessageHandler(MessageHandler listener)

Specified by:
  `addMessageHandler` in interface `Session`

#### 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 in milliseconds. Zero or negative values indicate an infinite timeout.

Specified by:
  `getMaxIdleTimeout` in interface `Session`

#### setMaxIdleTimeout

    public void setMaxIdleTimeout(long timeout)

Description copied from interface: `javax.websocket.Session`
Set the idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

Specified by:
  `setMaxIdleTimeout` in interface `Session`

#### setMaxBinaryMessageBufferSize

    public void setMaxBinaryMessageBufferSize(int max)

Description copied from interface: `javax.websocket.Session`
Set the current maximum buffer size (in bytes) for binary messages.

Specified by:
  `setMaxBinaryMessageBufferSize` in interface `Session`

#### getMaxBinaryMessageBufferSize

    public int getMaxBinaryMessageBufferSize()

Description copied from interface: `javax.websocket.Session`
Get the current maximum buffer size (in bytes) for binary messages.

Specified by:
  `getMaxBinaryMessageBufferSize` in interface `Session`

#### setMaxTextMessageBufferSize

    public void setMaxTextMessageBufferSize(int max)

Description copied from interface: `javax.websocket.Session`
Set the current maximum buffer size (in characters) for text messages.

Specified by:
  `setMaxTextMessageBufferSize` in interface `Session`

#### getMaxTextMessageBufferSize

    public int getMaxTextMessageBufferSize()

Description copied from interface: `javax.websocket.Session`
Get the current maximum buffer size (in characters) for text messages.

Specified by:
  `getMaxTextMessageBufferSize` in interface `Session`

#### getOpenSessions

    public Set<Session> getOpenSessions()

Description copied from interface: `javax.websocket.Session`
Obtain the set of currently open sessions for the local endpoint that this session is associated with.

Specified by:
  `getOpenSessions` in interface `Session`

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

#### 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`
Throws:
  `IOException`

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

#### appendCloseReasonWithTruncation

    protected static void appendCloseReasonWithTruncation(ByteBuffer msg,
                                       String reason)

Use protected so unit tests can access this method directly.

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

#### unregisterFuture

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

Remove a `FutureToSendHandler` from the set of tracked instances.

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

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