Module org.eclipse.jetty.websocket.api

Package org.eclipse.jetty.websocket.api

Interface Session.Listener

All Known Subinterfaces:

Session.Listener.AutoDemanding

All Known Implementing Classes:

Session.Listener.Abstract, Session.Listener.AbstractAutoDemanding

Enclosing interface:

Session

public static interface Session.Listener

The passive link of communication with a remote WebSocket endpoint.

Applications provide WebSocket endpoints that implement this interface to receive WebSocket events from the remote peer, and can use Session for configuration and to send WebSocket frames or messages to the other peer.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Session.Listener.Abstract
static class	Session.Listener.AbstractAutoDemanding
static interface	Session.Listener.AutoDemanding	Tag interface that signals that the WebSocket endpoint is demanding for WebSocket frames automatically.

Method Summary

Modifier and Type	Method	Description
default void	onWebSocketBinary(ByteBuffer payload, Callback callback)	A WebSocket BINARY message has been received.
default void	onWebSocketClose(int statusCode, String reason)	The WebSocket Session has been closed.
default void	onWebSocketError(Throwable cause)	A WebSocket error has occurred during the processing of WebSocket frames.
default void	onWebSocketFrame(Frame frame, Callback callback)	A WebSocket frame has been received.
default void	onWebSocketOpen(Session session)	A WebSocket Session has opened successfully and is ready to be used.
default void	onWebSocketPartialBinary(ByteBuffer payload, boolean last, Callback callback)	A WebSocket BINARY (or associated CONTINUATION) frame has been received.
default void	onWebSocketPartialText(String payload, boolean last)	A WebSocket TEXT (or associated CONTINUATION) frame has been received.
default void	onWebSocketPing(ByteBuffer payload)	A WebSocket PING frame has been received.
default void	onWebSocketPong(ByteBuffer payload)	A WebSocket PONG frame has been received.
default void	onWebSocketText(String message)	A WebSocket TEXT message has been received.

Method Details

onWebSocketOpen

default void onWebSocketOpen(Session session)

A WebSocket Session has opened successfully and is ready to be used.

Applications can store the given Session as a field so it can be used to send messages back to the other peer.

Parameters:

session - the WebSocket session

onWebSocketFrame

default void onWebSocketFrame(Frame frame,
 Callback callback)

A WebSocket frame has been received.

The received frames may be control frames such as PING, PONG or CLOSE, or data frames either BINARY or TEXT.

Parameters:

frame - the received frame

onWebSocketPing

default void onWebSocketPing(ByteBuffer payload)

A WebSocket PING frame has been received.

Parameters:

payload - the PING payload

onWebSocketPong

default void onWebSocketPong(ByteBuffer payload)

A WebSocket PONG frame has been received.

Parameters:

payload - the PONG payload

onWebSocketPartialBinary

default void onWebSocketPartialBinary(ByteBuffer payload,
 boolean last,
 Callback callback)

A WebSocket BINARY (or associated CONTINUATION) frame has been received.

The ByteBuffer is read-only, and will be recycled when the callback is completed.

Parameters:

payload - the BINARY frame payload

last - whether this is the last frame

callback - the callback to complete when the payload has been processed

onWebSocketPartialText

default void onWebSocketPartialText(String payload,
 boolean last)

A WebSocket TEXT (or associated CONTINUATION) frame has been received.

Parameters:

payload - the text message payload

Note that due to framing, there is a above average chance of any UTF8 sequences being split on the border between two frames will result in either the previous frame, or the next frame having an invalid UTF8 sequence, but the combined frames having a valid UTF8 sequence.

The String being provided here will not end in a split UTF8 sequence. Instead this partial sequence will be held over until the next frame is received.

last - whether this is the last frame

onWebSocketBinary

default void onWebSocketBinary(ByteBuffer payload,
 Callback callback)

A WebSocket BINARY message has been received.

Parameters:

payload - the raw payload array received

onWebSocketText

default void onWebSocketText(String message)

A WebSocket TEXT message has been received.

Parameters:

message - the text payload

onWebSocketError

default void onWebSocketError(Throwable cause)

A WebSocket error has occurred during the processing of WebSocket frames.

Usually errors occurs from bad or malformed incoming packets, for example text frames that do not contain UTF-8 bytes, frames that are too big, or other violations of the WebSocket specification.

The WebSocket Session will be closed, but applications may explicitly close the Session providing a different status code or reason.

Parameters:

cause - the error that occurred

onWebSocketClose

default void onWebSocketClose(int statusCode,
 String reason)

The WebSocket Session has been closed.

Parameters:

statusCode - the close status code

reason - the optional reason for the close