public static interface WebSocket.Listener
WebSocket
.
Each method below corresponds to a type of event.
onOpen
onText
, onBinary
, onPing
and onPong
onOpen
.
onClose
, onError
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 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 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.
|
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. 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.
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
exception.
onText
method.webSocket
- the WebSocketmessage
- the messagepart
- the partnull
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 this
exception.
webSocket
- the WebSocketmessage
- the messagepart
- the partnull
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 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.
Replies with a Pong message and requests one more message when the Pong has been sent.
webSocket
- the WebSocketmessage
- the messagenull
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
- the WebSocketmessage
- the messagenull
if already donedefault void onClose(WebSocket webSocket, Optional<WebSocket.CloseCode> code, String reason)
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.
webSocket
- the WebSocketcode
- an Optional
describing the close code, or
an empty Optional
if the message doesn't contain itreason
- the reason of close; can be emptydefault void onError(WebSocket webSocket, Throwable error)
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
.
sendX
methods are reported to
the CompletableFuture
these methods return.webSocket
- the WebSocketerror
- the error Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-internal+0-2016-10-04-161205.jjg.dev.8159855.tools-spi