Jetty 12.0.6 · org.eclipse.jetty.websocket.core.FrameHandler

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 and Description
public void	onClosed(CloseStatus the close status received from the remote peer, or generated locally in the case of abnormal closures. closeStatus, Callback the callback to indicate success or failure of the processing of this event. callback) Invoked when a WebSocket close event happened.
public void	onError(Throwable the error cause cause, Callback the callback to indicate success or failure of the processing of this event. callback) Invoked when an error has occurred or has been detected.
public void	onFrame(Frame the WebSocket frame. frame, Callback the callback to indicate success or failure of the processing of this event. callback) Redeclares org.eclipse.jetty.websocket.core.IncomingFrames.onFrame. Invoked when a WebSocket frame is received.
public void	onOpen(CoreSession the session associated with this connection. coreSession, Callback the callback to indicate success or failure of the processing of this event. callback) Invoked when the WebSocket connection is opened.

Method Detail

onClosed	back to summary
public 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:CloseStatus the close status received from the remote peer, or generated locally in the case of abnormal closures. callback:Callback the callback to indicate success or failure of the processing of this event.

onClosed

back to summary

public 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:CloseStatus: the close status received from the remote peer, or generated locally in the case of abnormal closures.
callback:Callback: the callback to indicate success or failure of the processing of this event.

onError back to summary

onError	back to summary
public 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:Throwable the error cause callback:Callback the callback to indicate success or failure of the processing of this event.

public 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:Throwable: the error cause
callback:Callback: the callback to indicate success or failure of the processing of this event.

onFrame back to summary

onFrame	back to summary
public void onFrame(Frame frame, Callback callback) Redeclares org.eclipse.jetty.websocket.core.IncomingFrames.onFrame. 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. Parameters frame:Frame the WebSocket frame. callback:Callback the callback to indicate success or failure of the processing of this event.

public void onFrame(Frame frame, Callback callback)

Redeclares org.eclipse.jetty.websocket.core.IncomingFrames.onFrame.

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.

Parameters

frame:Frame: the WebSocket frame.
callback:Callback: the callback to indicate success or failure of the processing of this event.

onOpen back to summary

onOpen	back to summary
public void onOpen(CoreSession coreSession, Callback callback) Invoked when the WebSocket connection is opened. It is allowed to send WebSocket frames via `CoreSession#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:CoreSession the session associated with this connection. callback:Callback the callback to indicate success or failure of the processing of this event.

public void onOpen(CoreSession coreSession, Callback callback)

Invoked when the WebSocket connection is opened.

It is allowed to send WebSocket frames via CoreSession#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:CoreSession: the session associated with this connection.
callback:Callback: the callback to indicate success or failure of the processing of this event.

public Interface FrameHandler

Method Summary

Method Detail