WsSession (Apache Tomcat 8.0.15 API Documentation)

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

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.
`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`	`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.
`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.
  - 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.
  - 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
    
    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()
```

Class WsSession

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

WsSession

Method Detail

getContainer

addMessageHandler

addMessageHandler

addMessageHandler

getMessageHandlers

removeMessageHandler

getProtocolVersion

getNegotiatedSubprotocol

getNegotiatedExtensions

isSecure

isOpen

getMaxIdleTimeout

setMaxIdleTimeout

setMaxBinaryMessageBufferSize

getMaxBinaryMessageBufferSize

setMaxTextMessageBufferSize

getMaxTextMessageBufferSize

getOpenSessions

getAsyncRemote

getBasicRemote

close

close

onClose

appendCloseReasonWithTruncation

registerFuture

unregisterFuture

getRequestURI

getRequestParameterMap

getQueryString

getUserPrincipal

getPathParameters

getId

getUserProperties

getLocal

getHttpSessionId

getTextMessageHandler

getBinaryMessageHandler

getPongMessageHandler

updateLastActive

checkExpiration