public static interface WebSocket.Listener
WebSocket
.
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
onText
, onBinary
, onPing
and onPong
onOpen
.
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.
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 null
s as their arguments.
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.
|
default void onOpen(WebSocket webSocket)
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.
webSocket.request(1);
webSocket
- the WebSocketdefault CompletionStage<?> onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)
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.
webSocket.request(1);
return null;
onText
method.webSocket
- the WebSocketmessage
- the messagepart
- the partCompletionStage
which completes when the message
processing is done; or null
if already donedefault CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)
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.
webSocket.request(1);
return null;
webSocket
- the WebSocketmessage
- the messagepart
- the partCompletionStage
which completes when the message
processing is done; or null
if already donedefault CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer 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.
webSocket.request(1);
return null;
webSocket
- the WebSocketmessage
- the messageCompletionStage
which completes when the message
processing is done; or null
if already donedefault CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer 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.
webSocket.request(1);
return null;
webSocket
- the WebSocketmessage
- the messageCompletionStage
which completes when the message
processing is done; or null
if already donedefault CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)
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.
return null;
webSocket
- the WebSocketstatusCode
- the status codereason
- the reasonCompletionStage
which completes when the
WebSocket
can be closed; or null
if it can be closed immediatelyWebSocket.NORMAL_CLOSURE
default void onError(WebSocket webSocket, Throwable error)
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.
CompletableFuture
s sendX
methods return, rather than
to this this method.webSocket
- the WebSocketerror
- the error Submit a bug or feature
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 2015, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-Ubuntu+0-9b153-1