WebSocket instances are created through WebSocket..
WebSocket has an input and an output side. These sides are independent
from each other. A side can either be open or closed. Once closed, the side
remains closed. WebSocket messages are sent through a WebSocket and
received through a WebSocket.Listener associated with it. Messages
can be sent until the WebSocket's output is closed, and received until the
WebSocket's input is closed.
A send method is any of the sendText, sendBinary,
sendPing, sendPong and sendClose methods of
WebSocket. A send method initiates a send operation and returns a
CompletableFuture which completes once the operation has completed.
If the CompletableFuture completes normally the operation is
considered succeeded. If the CompletableFuture completes
exceptionally, the operation is considered failed. An operation that has been
initiated but not yet completed is considered pending.
A receive method is any of the onText, onBinary,
onPing, onPong and onClose methods of
Listener. WebSocket initiates a receive operation by invoking a
receive method on the listener. The listener then must return a
CompletionStage which completes once the operation has completed.
To control receiving of messages, a WebSocket maintains an
internal counter. This counter's value is a number of
times the WebSocket has yet to invoke a receive method. While this counter is
zero the WebSocket does not invoke receive methods. The counter is
incremented by n when request(n) is called. The counter is
decremented by one when the WebSocket invokes a receive method.
onOpen and onError are not receive methods. WebSocket invokes
onOpen prior to any other methods on the listener. WebSocket invokes
onOpen at most once. WebSocket may invoke onError at any
given time. If the WebSocket invokes onError or onClose, then
no further listener's methods will be invoked, no matter the value of the
counter. For a newly built WebSocket the counter is zero.
Unless otherwise stated, null arguments will cause methods
of WebSocket to throw NullPointerException, similarly,
WebSocket will not pass null arguments to methods of
Listener. The state of a WebSocket is not changed by the invocations
that throw or return a CompletableFuture that completes with one of
the NullPointerException, IllegalArgumentException,
IllegalStateException exceptions.
WebSocket handles received Ping and Close messages automatically
(as per the WebSocket Protocol) by replying with Pong and Close messages. If
the listener receives Ping or Close messages, no mandatory actions from the
listener are required.
API Note
The relationship between a WebSocket and the associated Listener is
analogous to that of a Subscription and the associated Subscriber of type
java..
| Modifier and Type | Class and Description |
|---|---|
| public static interface | WebSocket.
A builder of WebSocket Clients. |
| public static interface | WebSocket.
The receiving interface of |
| Modifier and Type | Field and Description |
|---|---|
| public static final int | NORMAL_CLOSURE
The WebSocket Close message status code ( |
| Modifier and Type | Method and Description |
|---|---|
| public void | |
| public String | Returns: the subprotocol, or an empty string if there's no subprotocolReturns the subprotocol used by this WebSocket. |
| public boolean | Returns: true if closed, false otherwiseTells whether this WebSocket's input is closed. |
| public boolean | Returns: true if closed, false otherwiseTells whether this WebSocket's output is closed. |
| public void | |
| public CompletableFuture | Returns: aCompletableFuture that completes, with this WebSocket,
when the data has been sentthe data data, boolean true if this invocation completes the message,
false otherwiseSends binary data with bytes from the given buffer. |
| public CompletableFuture | |
| public CompletableFuture | Returns: aCompletableFuture that completes, with this WebSocket,
when the Ping message has been sentthe message message)Sends a Ping message with bytes from the given buffer. |
| public CompletableFuture | Returns: aCompletableFuture that completes, with this WebSocket,
when the Pong message has been sentthe message message)Sends a Pong message with bytes from the given buffer. |
| public CompletableFuture | Returns: aCompletableFuture that completes, with this WebSocket,
when the data has been sentthe data data, boolean true if this invocation completes the message,
false otherwiseSends textual data with characters from the given character sequence. |
| NORMAL_CLOSURE | back to summary |
|---|---|
| public static final int NORMAL_CLOSURE The WebSocket Close message status code ( | |
| abort | back to summary |
|---|---|
| public void abort() Closes this WebSocket's input and output abruptly. When this method returns both the input and the output will have been
closed. Any pending send operations will fail with | |
| getSubprotocol | back to summary |
|---|---|
| public String getSubprotocol() Returns the subprotocol used by this WebSocket.
| |
| isInputClosed | back to summary |
|---|---|
| public boolean isInputClosed() Tells whether this WebSocket's input is closed. If this method returns
| |
| isOutputClosed | back to summary |
|---|---|
| public boolean isOutputClosed() Tells whether this WebSocket's output is closed. If this method returns
| |
| request | back to summary |
|---|---|
| public void request(long n) Increments the counter of invocations of receive methods. This WebSocket will invoke API Note The parameter of this method is the number of invocations being
requested from this WebSocket to the associated listener, not the number
of messages. Sometimes a message may be delivered to the listener in a
single invocation, but not always. For example, Ping, Pong and Close
messages are delivered in a single invocation of Here is an example of a listener that requests invocations, one at a time, until a complete message has been accumulated, and then processes the result: WebSocket.Listener listener = new WebSocket.Listener() {
StringBuilder text = new StringBuilder();
public CompletionStage<?> onText(WebSocket webSocket,
CharSequence message,
boolean last) {
text.append(message);
if (last) {
processCompleteTextMessage(text);
text = new StringBuilder();
}
webSocket.request(1);
return null;
}
};
| |
| sendBinary | back to summary |
|---|---|
| public CompletableFuture Sends binary data with bytes from the given buffer. The data is located in bytes from the buffer's position to its limit.
Upon normal completion of a The
| |
| sendClose | back to summary |
|---|---|
| public CompletableFuture Initiates an orderly closure of this WebSocket's output by sending a Close message with the given status code and the reason. The A
Unless the If not already closed, the input remains open until a Close message
received, or
API Note Use the provided integer constant CompletableFuture<WebSocket> webSocket = ...
webSocket.thenCompose(ws -> ws.sendText("Hello, ", false))
.thenCompose(ws -> ws.sendText("world!", true))
.thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, ""))
.join();
sendClose method does not close this WebSocket's input. It
merely closes this WebSocket's output by sending a Close message. To
enforce closing the input, invoke the abort method. Here is an
example of an application that sends a Close message, and then starts a
timer. Once no data has been received within the specified timeout, the
timer goes off and the alarm aborts WebSocket:
MyAlarm alarm = new MyAlarm(webSocket::abort);
WebSocket.Listener listener = new WebSocket.Listener() {
public CompletionStage<?> onText(WebSocket webSocket,
CharSequence data,
boolean last) {
alarm.snooze();
...
}
...
};
...
Runnable startTimer = () -> {
MyTimer idleTimer = new MyTimer();
idleTimer.add(alarm, 30, TimeUnit.SECONDS);
};
webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer);
| |
| sendPing | back to summary |
|---|---|
| public CompletableFuture Sends a Ping message with bytes from the given buffer. The message consists of not more than The
| |
| sendPong | back to summary |
|---|---|
| public CompletableFuture Sends a Pong message with bytes from the given buffer. The message consists of not more than 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. The
| |
| sendText | back to summary |
|---|---|
| public CompletableFuture Sends textual data with characters from the given character sequence. The character sequence must not be modified until the
A
Implementation Note If
| |
Builders are created by invoking
HttpClient..
The intermediate (setter-like) methods change the state of the builder
and return the same builder they have been invoked on. If an intermediate
method is not invoked, an appropriate default value (or behavior) will be
assumed. A Builder is not safe for use by multiple threads
without external synchronization.
| Modifier and Type | Method and Description |
|---|---|
| public CompletableFuture | Returns: aCompletableFuture with the WebSocketthe WebSocket URI uri, WebSocket.the listener listenerBuilds a |
| public WebSocket. | Returns: this builderSets a timeout for establishing a WebSocket connection. |
| public WebSocket. | |
| public WebSocket. | Returns: this builderthe most preferred subprotocol mostPreferred, String... the lesser preferred subprotocols lesserPreferred)Sets a request for the given subprotocols. |
| buildAsync | back to summary |
|---|---|
| public CompletableFuture Builds a Returns a
| |
| connectTimeout | back to summary |
|---|---|
| public WebSocket. Sets a timeout for establishing a WebSocket connection. If the connection is not established within the specified
duration then building of the | |
| header | back to summary |
|---|---|
| public WebSocket. Adds the given name-value pair to the list of additional HTTP headers sent during the opening handshake. Headers defined in the WebSocket Protocol are illegal. If this method is not invoked, no additional HTTP headers will be sent. | |
| subprotocols | back to summary |
|---|---|
| public WebSocket. Sets a request for the given subprotocols. After the Subprotocols are specified in the order of preference. The most preferred subprotocol is specified first. If there are any additional subprotocols they are enumerated from the most preferred to the least preferred. Subprotocols not conforming to the syntax of subprotocol identifiers are illegal. If this method is not invoked then no subprotocols will be requested. | |
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.
API Note
The strict sequential order of invocations from
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.
CompletionStages 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 and Description |
|---|---|
| public default CompletionStage | Returns: aCompletionStage which completes when the
ByteBuffer may be reclaimed; or null if it may be
reclaimed immediatelythe WebSocket on which the data has been received webSocket, ByteBuffer the data data, boolean whether this invocation completes the message last)A binary data has been received. |
| public default CompletionStage | Returns: aCompletionStage which completes when the
WebSocket may be closed; or null if it may be
closed immediatelythe WebSocket on which the message has been received webSocket, int the status code statusCode, String the reason reason)Receives a Close message indicating the WebSocket's input has been closed. |
| public default void | |
| public default void | |
| public default CompletionStage | Returns: aCompletionStage which completes when the
ByteBuffer may be reclaimed; or null if it may be
reclaimed immediatelythe WebSocket on which the message has been received webSocket, ByteBuffer the message message)A Ping message has been received. |
| public default CompletionStage | Returns: aCompletionStage which completes when the
ByteBuffer may be reclaimed; or null if it may be
reclaimed immediatelythe WebSocket on which the message has been received webSocket, ByteBuffer the message message)A Pong message has been received. |
| public default CompletionStage | Returns: aCompletionStage which completes when the
CharSequence may be reclaimed; or null if it may be
reclaimed immediatelythe WebSocket on which the data has been received webSocket, CharSequence the data data, boolean whether this invocation completes the message last)A textual data has been received. |
| onBinary | back to summary |
|---|---|
| public default CompletionStage A binary data has been received. This data is located in bytes from the buffer's position to its limit. Return a Implementation Specification The default implementation is equivalent to: webSocket.request(1);
return null;
| |
| onClose | back to summary |
|---|---|
| public default CompletionStage Receives a Close message indicating the WebSocket's input has been closed. This is the last invocation from the specified A Close message consists of a status code and a reason for
closing. The status code is an integer from the range
If the WebSocket's output is not already closed, the
API Note Returning a To specify a custom closure code or reason code the
public CompletionStage<?> onClose(WebSocket webSocket,
int statusCode,
String reason) {
webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
return new CompletableFuture<Void>();
}
Implementation Specification The default implementation of this method returns
| |
| onError | back to summary |
|---|---|
| public default void onError(WebSocket webSocket, Throwable error) An error has occurred. 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 If an exception is thrown from this method, resulting behavior is undefined. | |
| onOpen | back to summary |
|---|---|
| public default void onOpen(WebSocket webSocket) A This is the initial invocation and it is made once. It is typically used to make a request for more invocations. Implementation Specification The default implementation is equivalent to: webSocket.request(1);
| |
| onPing | back to summary |
|---|---|
| public default CompletionStage A Ping message has been received. As guaranteed by the WebSocket Protocol, the message consists of
not more than 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 Implementation Specification The default implementation is equivalent to: webSocket.request(1);
return null;
| |
| onPong | back to summary |
|---|---|
| public default CompletionStage A Pong message has been received. As guaranteed by the WebSocket Protocol, the message consists of
not more than Return a Implementation Specification The default implementation is equivalent to: webSocket.request(1);
return null;
| |
| onText | back to summary |
|---|---|
| public default CompletionStage A textual data has been received. Return a Implementation Specification The default implementation is equivalent to: webSocket.request(1);
return null;
Implementation Note The
| |