WebSocket
public static interface WebSocket.Listener
WebSocket
. A WebSocket
invokes methods of the associated listener passing itself as an argument. These methods are invoked in a thread-safe manner, such that the next invocation may start only after the previous one has finished.
When data has been received, the WebSocket
invokes a receive method. Methods onText
, onBinary
, onPing
and onPong
must return a CompletionStage
that completes once the message has been received by the listener. If a listener's method returns null
rather than a CompletionStage
, WebSocket
will behave as if the listener returned a CompletionStage
that is already completed normally.
An IOException
raised in WebSocket
will result in an invocation of onError
with that exception (if the input is not closed). Unless otherwise stated if the listener's method throws an exception or a CompletionStage
returned from a method completes exceptionally, the WebSocket will invoke onError
with this exception.
WebSocket
to Listener
means, in particular, that the Listener
's methods are treated as non-reentrant. This means that Listener
implementations do not need to be concerned with possible recursion or the order in which they invoke WebSocket.request
in relation to their processing logic. Careful attention may be required if a listener is associated with more than a single WebSocket
. In this case invocations related to different instances of WebSocket
may not be ordered and may even happen concurrently.
CompletionStage
s returned from the receive methods have nothing to do with the counter of invocations. Namely, a CompletionStage
does not have to be completed in order to receive more invocations of the listener's methods. Here is an example of a listener that requests invocations, one at a time, until a complete message has been accumulated, then processes the result, and completes the CompletionStage
:
WebSocket.Listener listener = new WebSocket.Listener() {
List<CharSequence> parts = new ArrayList<>();
CompletableFuture<?> accumulatedMessage = new CompletableFuture<>();
public CompletionStage<?> onText(WebSocket webSocket,
CharSequence message,
boolean last) {
parts.add(message);
webSocket.request(1);
if (last) {
processWholeText(parts);
parts = new ArrayList<>();
accumulatedMessage.complete(null);
CompletionStage<?> cf = accumulatedMessage;
accumulatedMessage = new CompletableFuture<>();
return cf;
}
return accumulatedMessage;
}
};
Modifier and Type | Method | Description |
---|---|---|
default CompletionStage |
onBinary |
A binary data has been received. |
default CompletionStage |
onClose |
Receives a Close message indicating the WebSocket's input has been closed. |
default void |
onError |
An error has occurred. |
default void |
onOpen |
A WebSocket has been connected. |
default CompletionStage |
onPing |
A Ping message has been received. |
default CompletionStage |
onPong |
A Pong message has been received. |
default CompletionStage |
onText |
A textual data has been received. |
default void onOpen(WebSocket webSocket)
WebSocket
has been connected. This is the initial invocation and it is made once. It is typically used to make a request for more invocations.
webSocket.request(1);
webSocket
- the WebSocket that has been connecteddefault CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last)
Return a CompletionStage
which will be used by the WebSocket
as an indication it may reclaim the CharSequence
. Do not access the CharSequence
after this CompletionStage
has completed.
webSocket.request(1);
return null;
data
is always a legal UTF-16 sequence.webSocket
- the WebSocket on which the data has been receiveddata
- the datalast
- whether this invocation completes the messageCompletionStage
which completes when the CharSequence
may be reclaimed; or null
if it may be reclaimed immediatelydefault CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer data, boolean last)
This data is located in bytes from the buffer's position to its limit.
Return a CompletionStage
which will be used by the WebSocket
as an indication it may reclaim the ByteBuffer
. Do not access the ByteBuffer
after this CompletionStage
has completed.
webSocket.request(1);
return null;
webSocket
- the WebSocket on which the data has been receiveddata
- the datalast
- whether this invocation completes the messageCompletionStage
which completes when the ByteBuffer
may be reclaimed; or null
if it may be reclaimed immediatelydefault CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message)
As guaranteed by the WebSocket Protocol, the message consists of not more than 125
bytes. These bytes are located from the buffer's position to its limit.
Given that the WebSocket implementation will automatically send a reciprocal pong when a ping is received, it is rarely required to send a pong message explicitly when a ping is received.
Return a CompletionStage
which will be used by the WebSocket
as a signal it may reclaim the ByteBuffer
. Do not access the ByteBuffer
after this CompletionStage
has completed.
webSocket.request(1);
return null;
webSocket
- the WebSocket on which the message has been receivedmessage
- the messageCompletionStage
which completes when the ByteBuffer
may be reclaimed; or null
if it may be reclaimed immediatelydefault CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message)
As guaranteed by the WebSocket Protocol, the message consists of not more than 125
bytes. These bytes are located from the buffer's position to its limit.
Return a CompletionStage
which will be used by the WebSocket
as a signal it may reclaim the ByteBuffer
. Do not access the ByteBuffer
after this CompletionStage
has completed.
webSocket.request(1);
return null;
webSocket
- the WebSocket on which the message has been receivedmessage
- the messageCompletionStage
which completes when the ByteBuffer
may be reclaimed; or null
if it may be reclaimed immediatelydefault CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)
This is the last invocation from the specified WebSocket
. By the time this invocation begins the WebSocket's input will have been closed.
A Close message consists of a status code and a reason for closing. The status code is an integer from the range 1000 <= code <= 65535
. The reason
is a string which has a UTF-8 representation not longer than 123
bytes.
If the WebSocket's output is not already closed, the CompletionStage
returned by this method will be used as an indication that the WebSocket's output may be closed. The WebSocket will close its output at the earliest of completion of the returned CompletionStage
or invoking either of the sendClose
or abort
methods.
CompletionStage
that never completes, effectively disables the reciprocating closure of the output. To specify a custom closure code or reason code the sendClose
method may be invoked from inside the onClose
invocation:
public CompletionStage<?> onClose(WebSocket webSocket,
int statusCode,
String reason) {
webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
return new CompletableFuture<Void>();
}
null
, indicating that the output should be closed immediately.webSocket
- the WebSocket on which the message has been receivedstatusCode
- the status codereason
- the reasonCompletionStage
which completes when the WebSocket
may be closed; or null
if it may be closed immediatelydefault void onError(WebSocket webSocket, Throwable error)
This is the last invocation from the specified WebSocket. By the time this invocation begins both the WebSocket's input and output will have been closed. A WebSocket may invoke this method on the associated listener at any time after it has invoked onOpen
, regardless of whether or not any invocations have been requested from the WebSocket.
If an exception is thrown from this method, resulting behavior is undefined.
webSocket
- the WebSocket on which the error has occurrederror
- the error
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.net.http/java/net/http/WebSocket.Listener.html