Module java.httpclient

Package java.net.http

Interface WebSocket.Listener

Enclosing interface:

WebSocket

public static interface WebSocket.Listener

A listener for events and messages on a WebSocket.

Each method below corresponds to a type of event.

• onOpen
  This method is always the first to be invoked.
• onText, onBinary, onPing and onPong
  These methods are invoked zero or more times after onOpen.
• onClose, onError
  Only one of these methods is invoked, and that method is invoked last and at most once.

     onOpen (onText|onBinary|onPing|onPong)* (onClose|onError)?
 

Messages received by the Listener conform to the WebSocket Protocol, otherwise onError with a ProtocolException is invoked.

If a whole message is received, then the corresponding method (onText or onBinary) will be invoked with WHOLE marker. Otherwise the method will be invoked with FIRST, zero or more times with PART and, finally, with LAST markers.

     WHOLE|(FIRST PART* LAST)
 

All methods are invoked in a sequential (and happens-before) order, one after another, possibly by different threads. If any of the methods above throws an exception, onError is then invoked with that exception. Exceptions thrown from onError or onClose are ignored.

When the method returns, the message is deemed received. After this another messages may be received.

These invocations begin asynchronous processing which might not end with the invocation. To provide coordination, methods of Listener return a CompletionStage. The CompletionStage signals the WebSocket that the processing of a message has ended. For convenience, methods may return null, which means the same as returning an already completed CompletionStage. If the returned CompletionStage completes exceptionally, then onError will be invoked with the exception.

Control of the message passes to the Listener with the invocation of the method. Control of the message returns to the WebSocket at the earliest of, either returning null from the method, or the completion of the CompletionStage returned from the method. The WebSocket does not access the message while it's not in its control. The Listener must not access the message after its control has been returned to the WebSocket.

It is the responsibility of the listener to make additional message requests, when ready, so that messages are received eventually.

Methods above are never invoked with nulls as their arguments.

Since:

9

Method Summary

Modifier and Type	Method	Description
default CompletionStage<?>	onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)	Receives a Binary message.
default void	onClose(WebSocket webSocket, Optional<WebSocket.CloseCode> code, String reason)	Receives a Close message.
default void	onError(WebSocket webSocket, Throwable error)	Notifies an I/O or protocol error has occurred on the WebSocket.
default void	onOpen(WebSocket webSocket)	Notifies the Listener that it is connected to the provided WebSocket.
default CompletionStage<?>	onPing(WebSocket webSocket, ByteBuffer message)	Receives a Ping message.
default CompletionStage<?>	onPong(WebSocket webSocket, ByteBuffer message)	Receives a Pong message.
default CompletionStage<?>	onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)	Receives a Text message.

Method Detail

onOpen

default void onOpen(WebSocket webSocket)

Notifies the Listener that it is connected to the provided WebSocket.

The onOpen method does not correspond to any message from the WebSocket Protocol. It is a synthetic event. It is the first Listener's method to be invoked. No other Listener's methods are invoked before this one. The method is usually used to make an initial request for messages.

If an exception is thrown from this method then onError will be invoked with the exception.

Implementation Requirements:

The default implementation requests one message.

Parameters:

webSocket - the WebSocket

onText

default CompletionStage<?> onText(WebSocket webSocket,
                                  CharSequence message,
                                  WebSocket.MessagePart part)

Receives a Text message.

The onText method is invoked zero or more times between onOpen and (onClose or onError).

This message may be a partial UTF-16 sequence. However, the concatenation of all messages through the last will be a whole UTF-16 sequence.

If an exception is thrown from this method or the returned CompletionStage completes exceptionally, then onError will be invoked with the exception.

Implementation Requirements:

The default implementation requests one more message.

Implementation Note:

This implementation passes only complete UTF-16 sequences to the onText method.

Parameters:

webSocket - the WebSocket

message - the message

part - the part

Returns:

a CompletionStage that completes when the message processing is done; or null if already done

onBinary

default CompletionStage<?> onBinary(WebSocket webSocket,
                                    ByteBuffer message,
                                    WebSocket.MessagePart part)

Receives a Binary message.

The onBinary method is invoked zero or more times between onOpen and (onClose or onError).

If an exception is thrown from this method or the returned CompletionStage completes exceptionally, then onError will be invoked with this exception.

Implementation Requirements:

The default implementation requests one more message.

Parameters:

webSocket - the WebSocket

message - the message

part - the part

Returns:

a CompletionStage that completes when the message processing is done; or null if already done

onPing

default CompletionStage<?> onPing(WebSocket webSocket,
                                  ByteBuffer message)

Receives a Ping message.

A Ping message may be sent or received by either client or server. It may serve either as a keepalive or as a means to verify that the remote endpoint is still responsive.

The message will consist of not more than 125 bytes: message.remaining() <= 125.

The onPing is invoked zero or more times in between onOpen and (onClose or onError).

If an exception is thrown from this method or the returned CompletionStage completes exceptionally, then onError will be invoked with this exception.

Implementation Note:

Replies with a Pong message and requests one more message when the Pong has been sent.

Parameters:

webSocket - the WebSocket

message - the message

Returns:

a CompletionStage that completes when the message processing is done; or null if already done

onPong

default CompletionStage<?> onPong(WebSocket webSocket,
                                  ByteBuffer message)

Receives a Pong message.

A Pong message may be unsolicited or may be received in response to a previously sent Ping. In the latter case, the contents of the Pong is identical to the originating Ping.

The message will consist of not more than 125 bytes: message.remaining() <= 125.

The onPong method is invoked zero or more times in between onOpen and (onClose or onError).

If an exception is thrown from this method or the returned CompletionStage completes exceptionally, then onError will be invoked with this exception.

Implementation Requirements:

The default implementation requests one more message.

Parameters:

webSocket - the WebSocket

message - the message

Returns:

a CompletionStage that completes when the message processing is done; or null if already done

onClose

default void onClose(WebSocket webSocket,
                     Optional<WebSocket.CloseCode> code,
                     String reason)

Receives a Close message.

Once a Close message is received, the server will not send any more messages.

A Close message may consist of a status code and a reason for closing. The reason will have a UTF-8 representation not longer than 123 bytes. The reason may be useful for debugging or passing information relevant to the connection but is not necessarily human readable.

onClose is the last invocation on the Listener. It is invoked at most once, but after onOpen. If an exception is thrown from this method, it is ignored.

Implementation Requirements:

The default implementation does nothing.

Parameters:

webSocket - the WebSocket

code - an Optional describing the close code, or an empty Optional if the message doesn't contain it

reason - the reason of close; can be empty

onError

default void onError(WebSocket webSocket,
                     Throwable error)

Notifies an I/O or protocol error has occurred on the WebSocket.

The onError method does not correspond to any message from the WebSocket Protocol. It is a synthetic event. onError is the last invocation on the Listener. It is invoked at most once but after onOpen. If an exception is thrown from this method, it is ignored.

The WebSocket Protocol requires some errors occurs in the incoming destination must be fatal to the connection. In such cases the implementation takes care of closing the WebSocket. By the time onError is invoked, no more messages can be sent on this WebSocket.

API Note:

Errors associated with sendX methods are reported to the CompletableFuture these methods return.

Implementation Requirements:

The default implementation does nothing.

Parameters:

webSocket - the WebSocket

error - the error