Module org.eclipse.jetty.websocket.api

Package org.eclipse.jetty.websocket.api

Interface Session

All Superinterfaces:

AutoCloseable, Closeable, Configurable

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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Session.Listener	The passive link of communication with a remote WebSocket endpoint.

Method Summary

Modifier and Type	Method	Description
default void	close()	Equivalent to close(StatusCode.NORMAL, null, Callback.NOOP).
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.
void	demand()	Explicitly demands for WebSocket events.
void	disconnect()	Abruptly closes the WebSocket connection without sending a CLOSE frame.
SocketAddress	getLocalSocketAddress()
String	getProtocolVersion()	Returns the version of the WebSocket protocol currently being used.
SocketAddress	getRemoteSocketAddress()
UpgradeRequest	getUpgradeRequest()
UpgradeResponse	getUpgradeResponse()
boolean	isOpen()
boolean	isSecure()
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.
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.
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.
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.
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.
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.

Methods inherited from interface org.eclipse.jetty.websocket.api.Configurable

getIdleTimeout, getInputBufferSize, getMaxBinaryMessageSize, getMaxFrameSize, getMaxOutgoingFrames, getMaxTextMessageSize, getOutputBufferSize, isAutoFragment, setAutoFragment, setIdleTimeout, setInputBufferSize, setMaxBinaryMessageSize, setMaxFrameSize, setMaxOutgoingFrames, setMaxTextMessageSize, setOutputBufferSize

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(int, String, Callback)
• disconnect()

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:

• StatusCode
• close()
• disconnect()

disconnect

void disconnect()

Abruptly closes the WebSocket connection without sending a CLOSE frame.

See Also:

• close(int, String, Callback)

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