Package org.eclipse.jetty.websocket.api

Interface Session

All Superinterfaces:
AutoCloseable, Closeable, Configurable
All Known Implementing Classes:
WebSocketSession
public interface Session extends Configurable, Closeable

Session represents an active link of communication with a remote WebSocket endpoint.

Session APIs can be used to configure the various parameters that control the behavior of the WebSocket communication, such as Configurable.setMaxTextMessageSize(long), and to send WebSocket frames or messages to the other peer.

The passive link of communication that receives WebSocket events is Session.Listener.

  • Method Details

    • demand

      void demand()

      Explicitly demands for WebSocket events.

      This method should be called only when the WebSocket endpoint is not demanding automatically, as defined by WebSocket.autoDemand() and Session.Listener.AutoDemanding.

      In general, invoking this method results in a listener method or an annotated method to be called when the corresponding event is ready to be delivered.

      For WebSocket endpoints that wants to receive frame events (for example by overriding Session.Listener.onWebSocketFrame(Frame, Callback)), invoking this method will result in a frame event being delivered to the listener/annotated method when a new frame is received.

      For WebSocket endpoints that want to receive whole message events (for example by overriding Session.Listener.onWebSocketText(String)), invoking this method will result in a message event being delivered to the listener/annotated method when a new message is received. The implementation will automatically demand for more frames until a whole message is assembled and then deliver the whole message as event.

      Note that even when the WebSocket endpoint is interested in whole messages, calling this method is necessary not only to possibly receive the next whole message, but also to receive control frames (such as PING or CLOSE frames). Failing to call this method after receiving a whole message results in the CLOSE frame event to not be processed, and therefore for the endpoint to not notice when the other peer closed the WebSocket communication.

      Throws:
      IllegalStateException - if the WebSocket endpoint is auto-demanding

    • sendBinary

      void sendBinary(ByteBuffer buffer, Callback callback)

      Initiates the asynchronous send of a BINARY message, notifying the given callback when the message send is completed, either successfully or with a failure.

      Parameters:
      buffer - the message bytes to send
      callback - callback to notify when the send operation is complete

    • sendPartialBinary

      void sendPartialBinary(ByteBuffer buffer, boolean last, Callback callback)

      Initiates the asynchronous send of a BINARY frame, possibly part of a larger binary message, notifying the given callback when the frame send is completed, either successfully or with a failure.

      Non-final frames must be sent with the parameter last=false. The final frame must be sent with last=true.

      Parameters:
      buffer - the frame bytes to send
      last - whether this is the last frame of the message
      callback - callback to notify when the send operation is complete

    • sendText

      void sendText(String text, Callback callback)

      Initiates the asynchronous send of a TEXT message, notifying the given callback when the message send is completed, either successfully or with a failure.

      Parameters:
      text - the message text to send
      callback - callback to notify when the send operation is complete

    • sendPartialText

      void sendPartialText(String text, boolean last, Callback callback)

      Initiates the asynchronous send of a TEXT frame, possibly part of a larger binary message, notifying the given callback when the frame send is completed, either successfully or with a failure.

      Non-final frames must be sent with the parameter last=false. The final frame must be sent with last=true.

      Parameters:
      text - the frame text to send
      last - whether this is the last frame of the message
      callback - callback to notify when the send operation is complete

    • sendPing

      void sendPing(ByteBuffer applicationData, Callback callback)

      Initiates the asynchronous send of a PING frame, notifying the given callback when the frame send is completed, either successfully or with a failure.

      Parameters:
      applicationData - the data to be carried in the PING frame
      callback - callback to notify when the send operation is complete

    • sendPong

      void sendPong(ByteBuffer applicationData, Callback callback)

      Initiates the asynchronous send of a PONG frame, notifying the given callback when the frame send is completed, either successfully or with a failure.

      Parameters:
      applicationData - the data to be carried in the PONG frame
      callback - callback to notify when the send operation is complete

    • close

      default void close()

      Equivalent to close(StatusCode.NORMAL, null, Callback.NOOP).

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      See Also:

    • close

      void close(int statusCode, String reason, Callback callback)

      Sends a websocket CLOSE frame, with status code and reason, notifying the given callback when the frame send is completed, either successfully or with a failure.

      Parameters:
      statusCode - the status code
      reason - the (optional) reason
      callback - callback to notify when the send operation is complete
      See Also:

    • disconnect

      void disconnect()

      Abruptly closes the WebSocket connection without sending a CLOSE frame.

      See Also:

    • getLocalSocketAddress

      SocketAddress getLocalSocketAddress()
      Returns:
      the local SocketAddress for the connection, if available

    • getRemoteSocketAddress

      SocketAddress getRemoteSocketAddress()
      Returns:
      the remote SocketAddress for the connection, if available

    • getProtocolVersion

      String getProtocolVersion()

      Returns the version of the WebSocket protocol currently being used.

      This is taken as the value of the Sec-WebSocket-Version header used in the upgrade request.

      Returns:
      the WebSocket protocol version

    • getUpgradeRequest

      UpgradeRequest getUpgradeRequest()
      Returns:
      the UpgradeRequest used to create this session

    • getUpgradeResponse

      UpgradeResponse getUpgradeResponse()
      Returns:
      the UpgradeResponse used to create this session

    • isOpen

      boolean isOpen()
      Returns:
      whether the session is open

    • isSecure

      boolean isSecure()
      Returns:
      whether the underlying socket is using a secure transport