Module jdk.incubator.httpclient

Package jdk.incubator.http

Interface WebSocket.Listener

Enclosing interface:

WebSocket

public static interface WebSocket.Listener

A listener for events and messages on a WebSocket.
Incubating Feature. Will be removed in a future release.

Each method of Listener corresponds to a type of event or a type of message. The WebSocket argument of the method is the WebSocket the event has occurred (the message has been received) on. All methods with the same WebSocket argument are invoked in a sequential (and happens-before) order, one after another, possibly by different threads.

• onOpen
  This method is invoked first.
• 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.

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. If any of the methods above throws an exception, onError is then invoked with the same WebSocket and this exception. Exceptions thrown from onError or onClose are ignored.

When the method returns, the message is deemed received (in particular, if contained in a ByteBuffer buffer, the data is deemed received completely regardless of the result buffer.hasRemaining() upon the method's return. After this further 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 (by convention) means the same as returning an already completed (normally) CompletionStage. If the returned CompletionStage completes exceptionally, then onError will be invoked with the same WebSocket and this 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.

A WebSocket implementation never invokes Listener's methods 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 CompletionStage<?>	onClose(WebSocket webSocket, int statusCode, String reason)	Receives a Close message.
default void	onError(WebSocket webSocket, Throwable error)	Notifies an I/O or protocol error has occurred.
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 and the first Listener's method to be invoked.

This 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 same WebSocket and this exception.

Implementation Requirements:

The default implementation of this method behaves as if:

     webSocket.request(1);
 

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 same WebSocket and this exception.

Implementation Requirements:

The default implementation of this method behaves as if:

     webSocket.request(1);
     return null;
 

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 which 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 the same WebSocket and this exception.

Implementation Requirements:

The default implementation of this method behaves as if:

     webSocket.request(1);
     return null;
 

Parameters:

webSocket - the WebSocket

message - the message

part - the part

Returns:

a CompletionStage which 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 WebSocket handles Ping messages by replying with appropriate Pong messages using a strategy of its choice, but within the boundaries of the WebSocket Protocol. The WebSocket may invoke onPing after handling a Ping message, before doing so or in parallel with it. In other words no particular ordering is guaranteed. If an error occurs while implementation handles this Ping message, then onError will be invoked with this error. For more details on handling Ping messages see RFC 6455 sections 5.5.2. Ping and 5.5.3. Pong.

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 Requirements:

The default implementation of this method behaves as if:

     webSocket.request(1);
     return null;
 

Parameters:

webSocket - the WebSocket

message - the message

Returns:

a CompletionStage which 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 of this method behaves as if:

     webSocket.request(1);
     return null;
 

Parameters:

webSocket - the WebSocket

message - the message

Returns:

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

onClose

default CompletionStage<?> onClose(WebSocket webSocket,
                                   int statusCode,
                                   String reason)

Receives a Close message.

A Close message consists of a status code and a reason for closing. The status code is an integer in the range 1000 <= code <= 65535. The reason is a short string that has an UTF-8 representation not longer than 123 bytes. For more details on Close message, status codes and reason see RFC 6455 sections 5.5.1. Close and 7.4. Status Codes.

After the returned CompletionStage has completed (normally or exceptionally), the WebSocket completes the closing handshake by replying with an appropriate Close message.

This implementation replies with a Close message that has the same code this message has and an empty reason.

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.

The WebSocket will close at the earliest of completion of the returned CompletionStage or sending a Close message. In particular, if a Close message has been sent before, then this invocation completes the closing handshake and by the time this method is invoked, the WebSocket will have been closed.

Implementation Requirements:

The default implementation of this method behaves as if:

     return null;
 

Parameters:

webSocket - the WebSocket

statusCode - the status code

reason - the reason

Returns:

a CompletionStage which completes when the WebSocket can be closed; or null if it can be closed immediately

See Also:

WebSocket.NORMAL_CLOSURE

onError

default void onError(WebSocket webSocket,
                     Throwable error)

Notifies an I/O or protocol error has occurred.

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

Note that the WebSocket Protocol requires some errors occur in the incoming destination must be fatal to the connection. In such cases the implementation takes care of Failing the WebSocket Connection: by the time onError is invoked, the WebSocket will have been closed. Any outstanding or subsequent send operation will complete exceptionally with an IOException. For more details on Failing the WebSocket Connection see RFC 6455 section 7.1.7. Fail the WebSocket Connection.

API Note:

Errors associated with sending messages are reported to the CompletableFutures sendX methods return, rather than to this this method.

Implementation Requirements:

The default implementation of this method does nothing.

Parameters:

webSocket - the WebSocket

error - the error