public interface WebSocket
A WebSocket
provides full-duplex communication over a TCP
connection.
To create a WebSocket
use a builder. Once a WebSocket
is built, it's ready
to send and receive messages. When the WebSocket
is no longer needed
it must be closed: a Close message must both be sent and received.
The WebSocket
may be also closed abruptly.
Once closed the WebSocket
remains closed
and cannot be reopened.
Messages of type X
(where X
is one of: Text, Binary,
Ping, Pong or Close) are sent and received asynchronously through the
WebSocket.send{X}
and WebSocket.Listener
.on{X}
methods
respectively. Each method returns a CompletionStage
which completes
when the operation has completed.
Note that messages (of any type) are received only if requested.
One outstanding send operation is permitted. No further send operation
can be initiated before the previous one has completed. When sending, a
message must not be modified until the returned CompletableFuture
completes (either normally or exceptionally).
Text and Binary messages can be sent and received as a whole or in parts. A whole message is transferred as a sequence of one or more invocations of a corresponding method where the last invocation is identified via an additional method argument.
If the message is contained in a ByteBuffer
, bytes are considered
arranged from the buffer
's position
to
the buffer
's limit
.
Unless otherwise stated, null
parameter values will cause methods
and constructors to throw NullPointerException
.
CompletableFuture
.Modifier and Type | Interface | Description |
---|---|---|
static interface |
WebSocket.Builder |
A builder for creating
WebSocket instances. |
static interface |
WebSocket.Listener |
A listener for events and messages on a
WebSocket . |
static class |
WebSocket.MessagePart |
A marker used by
WebSocket.Listener in cases where a partial
message may be received. |
Modifier and Type | Field | Description |
---|---|---|
static int |
CLOSED_ABNORMALLY |
The WebSocket Close message status code (
1006 ), is
designated for use in applications expecting a status code to indicate
that the connection was closed abnormally, e.g., without sending or
receiving a Close message. |
static int |
NORMAL_CLOSURE |
The WebSocket Close message status code (
1000 ),
indicating normal closure, meaning that the purpose for which the
connection was established has been fulfilled. |
Modifier and Type | Method | Description |
---|---|---|
void |
abort() |
Closes the
WebSocket abruptly. |
String |
getSubprotocol() |
Returns a subprotocol
which has been chosen for this
WebSocket . |
boolean |
isClosed() |
Tells whether the
WebSocket is closed. |
void |
request(long n) |
Allows
n more messages to be received by the Listener . |
CompletableFuture<WebSocket> |
sendBinary(ByteBuffer message,
boolean isLast) |
Sends a Binary message with bytes from the given
ByteBuffer . |
CompletableFuture<WebSocket> |
sendClose() |
Sends an empty Close message.
|
CompletableFuture<WebSocket> |
sendClose(int statusCode,
String reason) |
Sends a Close message with the given status code and the reason.
|
CompletableFuture<WebSocket> |
sendPing(ByteBuffer message) |
Sends a Ping message with bytes from the given ByteBuffer.
|
CompletableFuture<WebSocket> |
sendPong(ByteBuffer message) |
Sends a Pong message with bytes from the given ByteBuffer.
|
default CompletableFuture<WebSocket> |
sendText(CharSequence message) |
Sends a whole Text message with characters from the given
CharSequence . |
CompletableFuture<WebSocket> |
sendText(CharSequence message,
boolean isLast) |
Sends a Text message with characters from the given
CharSequence . |
static final int NORMAL_CLOSURE
1000
),
indicating normal closure, meaning that the purpose for which the
connection was established has been fulfilled.static final int CLOSED_ABNORMALLY
1006
), is
designated for use in applications expecting a status code to indicate
that the connection was closed abnormally, e.g., without sending or
receiving a Close message.CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast)
CharSequence
.
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
The CharSequence
must not be modified until the returned
CompletableFuture
completes (either normally or exceptionally).
The returned CompletableFuture
can complete exceptionally
with:
IllegalArgumentException
-
if message
is a malformed UTF-16 sequence
IllegalStateException
-
if the WebSocket
is closed;
or if a Close message has been sent;
or if there is an outstanding send operation;
or if a previous Binary message was sent with isLast == false
IOException
-
if an I/O error occurs during this operation;
or if the WebSocket
has been closed due to an error;
CompletableFuture
completes exceptionally with IOException
.message
- the messageisLast
- true
if this is the last part of the message,
false
otherwiseCompletableFuture
with this WebSocket
default CompletableFuture<WebSocket> sendText(CharSequence message)
CharSequence
.
This is a convenience method. For the general case, use sendText(CharSequence, boolean)
.
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
The CharSequence
must not be modified until the returned
CompletableFuture
completes (either normally or exceptionally).
The returned CompletableFuture
can complete exceptionally
with:
IllegalArgumentException
-
if message
is a malformed UTF-16 sequence
IllegalStateException
-
if the WebSocket
is closed;
or if a Close message has been sent;
or if there is an outstanding send operation;
or if a previous Binary message was sent with isLast == false
IOException
-
if an I/O error occurs during this operation;
or if the WebSocket
has been closed due to an error;
message
- the messageCompletableFuture
with this WebSocket
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast)
ByteBuffer
.
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
The returned CompletableFuture
can complete exceptionally
with:
IllegalStateException
-
if the WebSocket
is closed;
or if a Close message has been sent;
or if there is an outstanding send operation;
or if a previous Text message was sent with isLast == false
IOException
-
if an I/O error occurs during this operation;
or if the WebSocket
has been closed due to an error
message
- the messageisLast
- true
if this is the last part of the message,
false
otherwiseCompletableFuture
with this WebSocket
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
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 must consist of not more than 125
bytes:
message.remaining() <= 125
.
The returned CompletableFuture
can complete exceptionally
with:
IllegalArgumentException
-
if message.remaining() > 125
IllegalStateException
-
if the WebSocket
is closed;
or if a Close message has been sent;
or if there is an outstanding send operation
IOException
-
if an I/O error occurs during this operation;
or if the WebSocket
has been closed due to an error
message
- the messageCompletableFuture
with this WebSocket
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
A Pong message may be unsolicited or may be sent in response to a previously received Ping. In latter case the contents of the Pong must be identical to the originating Ping.
The message must consist of not more than 125
bytes:
message.remaining() <= 125
.
The returned CompletableFuture
can complete exceptionally
with:
IllegalArgumentException
-
if message.remaining() > 125
IllegalStateException
-
if the WebSocket
is closed;
or if a Close message has been sent;
or if there is an outstanding send operation
IOException
-
if an I/O error occurs during this operation;
or if the WebSocket
has been closed due to an error
message
- the messageCompletableFuture
with this WebSocket
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
When this method has been invoked, no further messages can be sent.
The statusCode
is an integer in the range 1000 <= code
<= 4999
. However, not all status codes may be legal in some
implementations. Regardless of an implementation,
1000
is always legal and 1002
, 1003
, 1005
,
1006
, 1007
, 1009
, 1010
, 1012
,
1013
and 1015
are always illegal codes.
The reason
is a short string that must have 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.
The method returns a CompletableFuture<WebSocket>
which
completes normally when the message has been sent or completes
exceptionally if an error occurs.
The returned CompletableFuture
can complete exceptionally
with:
IllegalArgumentException
-
if the statusCode
has an illegal value;
or if reason
doesn't have an UTF-8 representation of
length <= 123
IOException
-
if an I/O error occurs during this operation;
or the WebSocket
has been closed due to an error
If this method has already been invoked or the WebSocket
is
closed, then subsequent invocations of this method have no effect and the
returned CompletableFuture
completes normally.
If a Close message has been received before, then this invocation completes the closing
handshake and by the time the returned CompletableFuture
completes, the WebSocket
will have been closed.
statusCode
- the status codereason
- the reasonCompletableFuture
with this WebSocket
sendClose()
CompletableFuture<WebSocket> sendClose()
When this method has been invoked, no further messages can be sent.
For more details on Close message see RFC 6455 section 5.5.1. Close
The method returns a CompletableFuture<WebSocket>
which
completes normally when the message has been sent or completes
exceptionally if an error occurs.
The returned CompletableFuture
can complete exceptionally
with:
IOException
-
if an I/O error occurs during this operation;
or the WebSocket
has been closed due to an error
If this method has already been invoked or the WebSocket
is
closed, then subsequent invocations of this method have no effect and the
returned CompletableFuture
completes normally.
If a Close message has been received before, then this invocation completes the closing
handshake and by the time the returned CompletableFuture
completes, the WebSocket
will have been closed.
CompletableFuture
with this WebSocket
sendClose(int, String)
void request(long n)
n
more messages to be received by the Listener
.
The actual number of received messages might be fewer if a Close
message is received, the WebSocket
closes or an error occurs.
A WebSocket
that has just been built, hasn't requested
anything yet. Usually the initial request for messages is made in Listener.onOpen
.
If the WebSocket
is closed then invoking this method has no
effect.
If a server sends more messages than requested, this implementation queues up these messages on the TCP connection and may eventually force the sender to stop sending through TCP flow control.
n
- the number of messagesIllegalArgumentException
- if n < 0
String getSubprotocol()
WebSocket
.String
if there is noneboolean isClosed()
WebSocket
is closed.
When a WebSocket
is closed no further messages can be sent or
received.
true
if the WebSocket
is closed,
false
otherwisevoid abort() throws IOException
WebSocket
abruptly.
This method may be invoked at any time. This method closes the
underlying TCP connection and puts the WebSocket
into a closed
state.
As the result Listener.onClose
will be invoked with the status code CLOSED_ABNORMALLY
unless either onClose
or onError
has been invoked before.
In which case no additional invocation will happen.
If the WebSocket
is already closed then invoking this method
has no effect.
IOException
- if an I/O error occurs 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-9b154-1