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

    • 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

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