Package org.eclipse.jetty.websocket.core

Interface FrameHandler

All Superinterfaces:
IncomingFrames
All Known Implementing Classes:
JakartaWebSocketFrameHandler, JettyWebSocketFrameHandler, MessageHandler
public interface FrameHandler extends IncomingFrames

Handles incoming WebSocket frames for a given endpoint.

FrameHandler is the receiver of parsed WebSocket frames. It is implemented by application code as the primary API to interact with the WebSocket implementation.

The FrameHandler instance to be used for each WebSocket connection is instantiated by the application, either:

  • On the server, the application must provide a WebSocketNegotiator to negotiate and accept WebSocket connections, which will return the FrameHandler instance from WebSocketNegotiator#negotiate(Negotiation).
  • On the client, the application returns the FrameHandler instance from the CoreClientUpgradeRequest instance passed to WebSocketCoreClient#connect(ClientUpgradeRequest).

Once instantiated the FrameHandler is used as follows:

  • The onOpen(CoreSession, Callback) method is called when negotiation of the connection is completed. The CoreSession argument is used to configure the connection, to obtain information about the connection, and to send frames
  • Every data and control frame received is passed to onFrame(Frame, Callback).
  • Received control frames that require a response (e.g. PING, CLOSE) are first passed to onFrame(Frame, Callback) to give the application an opportunity to respond explicitly. If a response has not been sent when the callback argument is completed, then the implementation will generate a response.
  • If an error is detected or received, then onError(Throwable, Callback) will be called to inform the application of the cause of the problem. The connection will then be closed or aborted and then onClosed(CloseStatus, Callback) will be called.
  • The onClosed(CloseStatus, Callback) method is always called once a WebSocket connection is terminated, either gracefully or not. The error code will indicate the nature of the close.

FrameHandler is responsible to manage the demand for more WebSocket frames, either directly by calling CoreSession.demand() or by delegating the demand management to other components.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onClosed(CloseStatus closeStatus, Callback callback)
    Invoked when a WebSocket close event happened.
    void
    onError(Throwable cause, Callback callback)
    Invoked when an error has occurred or has been detected.
    void
    onFrame(Frame frame, Callback callback)
    Invoked when a WebSocket frame is received.
    void
    onOpen(CoreSession coreSession, Callback callback)
    Invoked when the WebSocket connection is opened.

  • Method Details

    • onOpen

      void onOpen(CoreSession coreSession, Callback callback)

      Invoked when the WebSocket connection is opened.

      It is allowed to send WebSocket frames via OutgoingFrames.sendFrame(Frame, Callback, boolean).

      WebSocket frames cannot be received until a call to CoreSession.demand() is made.

      If the callback argument is failed, the implementation sends a CLOSE frame with CloseStatus.SERVER_ERROR, and the connection will be closed.

      Parameters:
      coreSession - the session associated with this connection.
      callback - the callback to indicate success or failure of the processing of this event.

    • onFrame

      void onFrame(Frame frame, Callback callback)

      Invoked when a WebSocket frame is received.

      This method will never be called concurrently for the same session; will be called sequentially to satisfy the outstanding demand signaled by calls to CoreSession.demand().

      Both control and data frames are passed to this method.

      CLOSE frames may be responded from this method, but if they are not responded, then the implementation will respond when the callback is completed.

      The callback argument must be completed to indicate that the buffers associated with the frame can be recycled.

      Additional WebSocket frames (of any type, including CLOSE frames) cannot be received until a call to CoreSession.demand() is made.

      Specified by:
      onFrame in interface IncomingFrames
      Parameters:
      frame - the WebSocket frame.
      callback - the callback to indicate success or failure of the processing of this event.

    • onError

      void onError(Throwable cause, Callback callback)

      Invoked when an error has occurred or has been detected.

      A call to this method will be followed by a call to onClosed(CloseStatus, Callback) with the close status derived from the error.

      This method will not be called more than once, onClosed(CloseStatus, Callback) will be called on the callback completion.

      Parameters:
      cause - the error cause
      callback - the callback to indicate success or failure of the processing of this event.

    • onClosed

      void onClosed(CloseStatus closeStatus, Callback callback)

      Invoked when a WebSocket close event happened.

      The WebSocket connection is closed, no reading or writing is possible anymore.

      Implementations of this method may cleanup resources that have been allocated.

      This method will not be called more than once.

      Parameters:
      closeStatus - the close status received from the remote peer, or generated locally in the case of abnormal closures.
      callback - the callback to indicate success or failure of the processing of this event.