Package org.eclipse.jetty.websocket.core

Interface FrameHandler

All Superinterfaces:
IncomingFrames
All Known Implementing Classes:
JakartaWebSocketFrameHandler, JettyWebSocketFrameHandler, MessageHandler
public interface FrameHandler extends IncomingFrames
Interface for local WebSocket Endpoint Frame handling.

This is the receiver of Parsed Frames. It is implemented by the Application (or Application API layer or Framework) as the primary API to/from the Core websocket implementation. The instance to be used for each websocket connection is instantiated by the application, either:

  • On the server, the application layer must provide a org.eclipse.jetty.websocket.core.server.WebSocketNegotiator instance to negotiate and accept websocket connections, which will return the FrameHandler instance to use from org.eclipse.jetty.websocket.core.server.WebSocketNegotiator#negotiate(Negotiation).
  • On the client, the application returns the FrameHandler instance to user from the ClientUpgradeRequest instance that it passes to the org.eclipse.jetty.websocket.core.client.WebSocketCoreClient#connect(ClientUpgradeRequest) method/

Once instantiated the FrameHandler follows is used as follows:

  • The onOpen(CoreSession, Callback) method is called when negotiation of the connection is completed. The passed CoreSession instance is used 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 (eg Ping, Close) are first passed to the onFrame(Frame, Callback) to give the Application an opportunity to send the response itself. If an appropriate response has not been sent when the callback passed is completed, then a response will be generated.
  • 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 the onClosed(CloseStatus, Callback) method 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    isDemanding()
    Does the FrameHandler manage it's own demand?
    void
    onClosed(CloseStatus closeStatus, Callback callback)
    This is the Close Handshake Complete event.
    void
    onError(Throwable cause, Callback callback)
    An error has occurred or been detected in websocket-core and being reported to FrameHandler.
    void
    onFrame(Frame frame, Callback callback)
    Receiver of all Frames.
    void
    onOpen(CoreSession coreSession, Callback callback)
    Async notification that Connection is being opened.

  • Method Details

    • onOpen

      void onOpen(CoreSession coreSession, Callback callback)
      Async notification that Connection is being opened.

      FrameHandler can write during this call, but can not receive frames until the callback is succeeded.

      If the FrameHandler succeeds the callback we transition to OPEN state and can now receive frames if not demanding, or can now call CoreSession.demand(long) to receive frames if demanding. If the FrameHandler fails the callback a close frame will be sent with CloseStatus.SERVER_ERROR and the connection will be closed.

      Parameters:
      coreSession - the session associated with this connection.
      callback - the callback to indicate success in processing (or failure)

    • onFrame

      void onFrame(Frame frame, Callback callback)
      Receiver of all Frames. This method will never be called in parallel for the same session and will be called sequentially to satisfy all outstanding demand signaled by calls to CoreSession.demand(long). Control and Data frames are passed to this method. Close frames may be responded to by the handler, but if an appropriate close response is not sent once the callback is succeeded, then a response close will be generated and sent.
      Specified by:
      onFrame in interface IncomingFrames
      Parameters:
      frame - the raw frame
      callback - the callback to indicate success in processing frame (or failure)

    • onError

      void onError(Throwable cause, Callback callback)
      An error has occurred or been detected in websocket-core and being reported to FrameHandler. A call to onError will be followed by a call to onClosed(CloseStatus, Callback) giving the close status derived from the error. This will not be called more than once, onClosed(CloseStatus, Callback) will be called on the callback completion.
      Parameters:
      cause - the reason for the error
      callback - the callback to indicate success in processing (or failure)

    • onClosed

      void onClosed(CloseStatus closeStatus, Callback callback)
      This is the Close Handshake Complete event.

      The connection is now closed, no reading or writing is possible anymore. Implementations of FrameHandler can cleanup their resources for this connection now. This method will be called only once.

      Parameters:
      closeStatus - the close status received from remote, or in the case of abnormal closure from local.
      callback - the callback to indicate success in processing (or failure)

    • isDemanding

      default boolean isDemanding()
      Does the FrameHandler manage it's own demand?
      Returns:
      true iff the FrameHandler will manage its own flow control by calling CoreSession.demand(long) when it is willing to receive new Frames. Otherwise the demand will be managed by an automatic call to demand(1) after every succeeded callback passed to onFrame(Frame, Callback).