Interface Session

All Superinterfaces:
AutoCloseable, Closeable
public interface Session extends Closeable
Represents a WebSocket session, which is the WebSocket connection between a client and a server. A session is created when a WebSocket connection is established and is used to send and receive messages.

  • Method Details

    • getContainer

      WebSocketContainer getContainer()
      Get the container that created this session.
      Returns:
      the container that created this session.

    • addMessageHandler

      void addMessageHandler(MessageHandler handler) throws IllegalStateException
      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 addMessageHandler(Class, jakarta.websocket.MessageHandler.Partial) or addMessageHandler(Class, jakarta.websocket.MessageHandler.Whole).
      Parameters:
      handler - The message handler for an incoming message
      Throws:
      IllegalStateException - If a message handler has already been registered for the associated message type

    • getMessageHandlers

      Set<MessageHandler> getMessageHandlers()
      Returns the set of message handlers currently registered on this session.
      Returns:
      The set of registered message handlers

    • removeMessageHandler

      void removeMessageHandler(MessageHandler listener)
      Removes the specified message handler from this session.
      Parameters:
      listener - The message handler to remove

    • getProtocolVersion

      String getProtocolVersion()
      Returns the version of the WebSocket protocol in use for this session.
      Returns:
      The protocol version

    • getNegotiatedSubprotocol

      String getNegotiatedSubprotocol()
      Returns the sub-protocol negotiated for this session, or null if no sub-protocol was negotiated.
      Returns:
      The negotiated sub-protocol

    • getNegotiatedExtensions

      List<Extension> getNegotiatedExtensions()
      Returns the list of extensions negotiated for this session.
      Returns:
      The list of negotiated extensions

    • isSecure

      boolean isSecure()
      Returns whether this session is using a secure connection (wss://).
      Returns:
      true if the connection is secure

    • isOpen

      boolean isOpen()
      Returns whether this session is currently open.
      Returns:
      true if the session is open

    • getMaxIdleTimeout

      long getMaxIdleTimeout()
      Get the idle timeout for this session.
      Returns:
      The current idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

    • setMaxIdleTimeout

      void setMaxIdleTimeout(long timeout)
      Set the idle timeout for this session.
      Parameters:
      timeout - The new idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

    • setMaxBinaryMessageBufferSize

      void setMaxBinaryMessageBufferSize(int max)
      Set the current maximum buffer size for binary messages.
      Parameters:
      max - The new maximum buffer size in bytes

    • getMaxBinaryMessageBufferSize

      int getMaxBinaryMessageBufferSize()
      Get the current maximum buffer size for binary messages.
      Returns:
      The current maximum buffer size in bytes

    • setMaxTextMessageBufferSize

      void setMaxTextMessageBufferSize(int max)
      Set the maximum buffer size for text messages.
      Parameters:
      max - The new maximum buffer size in characters.

    • getMaxTextMessageBufferSize

      int getMaxTextMessageBufferSize()
      Get the maximum buffer size for text messages.
      Returns:
      The maximum buffer size in characters.

    • getAsyncRemote

      RemoteEndpoint.Async getAsyncRemote()
      Returns the asynchronous remote endpoint for this session, used for non-blocking message sending.
      Returns:
      The asynchronous remote endpoint

    • getBasicRemote

      RemoteEndpoint.Basic getBasicRemote()
      Returns the synchronous remote endpoint for this session, used for blocking message sending.
      Returns:
      The synchronous remote endpoint

    • getId

      String getId()
      Provides a unique identifier for the session. This identifier should not be relied upon to be generated from a secure random source.
      Returns:
      A unique identifier for the session.

    • close

      void close() throws IOException
      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
      Throws:
      IOException - if an I/O error occurs while the WebSocket session is being closed.

    • close

      void close(CloseReason closeReason) throws IOException
      Close the connection to the remote end point using the specified code and reason phrase.
      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.

    • getRequestURI

      URI getRequestURI()
      Returns the URI of the request that initiated this WebSocket session.
      Returns:
      The request URI

    • getRequestParameterMap

      Map<String, List<String>> getRequestParameterMap()
      Returns the query parameters from the request that initiated this WebSocket session.
      Returns:
      The query parameter map

    • getQueryString

      String getQueryString()
      Returns the query string from the request that initiated this WebSocket session.
      Returns:
      The query string

    • getPathParameters

      Map<String,String> getPathParameters()
      Returns the path parameters extracted from the request URI using the endpoint's URI template.
      Returns:
      The path parameter map

    • getUserProperties

      Map<String,Object> getUserProperties()
      Returns a map of user properties associated with this session.
      Returns:
      The user properties map

    • getUserPrincipal

      Principal getUserPrincipal()
      Returns the principal of the user associated with this session, or null if the user is not authenticated.
      Returns:
      The user principal

    • getOpenSessions

      Set<Session> getOpenSessions()
      Obtain the set of open sessions associated with the same local endpoint as this session.
      Returns:
      The set of currently open sessions for the local endpoint that this session is associated with.

    • addMessageHandler

      <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) throws IllegalStateException
      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).
      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 an incoming message
      Throws:
      IllegalStateException - If a message handler has already been registered for the associated message type
      Since:
      WebSocket 1.1

    • addMessageHandler

      <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) throws IllegalStateException
      Registers a MessageHandler for whole incoming messages. Only one MessageHandler may be registered for each message type (text, binary, pong).
      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 an incoming message
      Throws:
      IllegalStateException - If a message handler has already been registered for the associated message type
      Since:
      WebSocket 1.1