public interface WebSocket
A WebSocket
provides full-duplex communication over a TCP
connection.
To create a WebSocket
use a builder. Once a WebSocket
is obtained, 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. Otherwise, invoke abort
to close abruptly.
Once closed the WebSocket
remains closed and cannot be reopened.
Messages of type X
are sent through the WebSocket.sendX
methods and received through WebSocket.Listener
.onX
methods
asynchronously. Each of the methods returns a CompletionStage
which
completes when the operation has completed.
Messages are received only if requested.
One outstanding send operation is permitted: if another send operation is
initiated before the previous one has completed, an IllegalStateException
will be thrown. When sending, a
message should not be modified until the returned CompletableFuture
completes (either normally or exceptionally).
Messages can be sent and received as a whole or in parts. A whole message is a sequence of one or more messages in which the last message is marked when it is sent or received.
If the message is contained in a ByteBuffer
, bytes are considered
arranged from the buffer
's position
to
the buffer
's limit
.
Unless otherwise noted, passing a null
argument to a constructor
or method of this type will cause a NullPointerException
to be thrown.
CompletableFuture
.Modifier and Type | Interface | Description |
---|---|---|
static interface |
WebSocket.Builder |
A builder for creating
WebSocket instances. |
static class |
WebSocket.CloseCode |
A
WebSocket close status code. |
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 | Method | Description |
---|---|---|
void |
abort() |
Closes the
WebSocket abruptly. |
String |
getSubprotocol() |
Returns a subprotocol
in use.
|
boolean |
isClosed() |
Tells whether the
WebSocket is closed. |
static WebSocket.Builder |
newBuilder(URI uri,
HttpClient client,
WebSocket.Listener listener) |
Creates a builder of
WebSocket s connected to the given URI and
receiving events with the given Listener . |
static WebSocket.Builder |
newBuilder(URI uri,
WebSocket.Listener listener) |
Creates a builder of
WebSocket s connected to the given URI and
receiving events with the given Listener . |
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(WebSocket.CloseCode code,
CharSequence reason) |
Sends a Close message with the given close code and the reason.
|
CompletableFuture<WebSocket> |
sendPing(ByteBuffer message) |
Sends a Ping message.
|
CompletableFuture<WebSocket> |
sendPong(ByteBuffer message) |
Sends a Pong message.
|
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 WebSocket.Builder newBuilder(URI uri, WebSocket.Listener listener)
WebSocket
s connected to the given URI and
receiving events with the given Listener
.
Equivalent to:
WebSocket.newBuilder(uri, HttpClient.getDefault())
uri
- the WebSocket URI as defined in the WebSocket Protocol
(with "ws" or "wss" scheme)listener
- the listenerIllegalArgumentException
- if the uri
is not a WebSocket URISecurityException
- if running under a security manager and the caller does
not have permission to access the
default HttpClientstatic WebSocket.Builder newBuilder(URI uri, HttpClient client, WebSocket.Listener listener)
WebSocket
s connected to the given URI and
receiving events with the given Listener
.
Providing a custom client
allows for finer control over the
opening handshake.
Example
HttpClient client = HttpClient.create()
.proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
.build();
...
WebSocket.newBuilder(URI.create("ws://websocket.example.com"), client, listener)...
uri
- the WebSocket URI as defined in the WebSocket Protocol
(with "ws" or "wss" scheme)client
- the HttpClientlistener
- the listenerIllegalArgumentException
- if the uri is not a WebSocket URICompletableFuture<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
should not be modified until the returned
CompletableFuture
completes (either normally or exceptionally).
The returned CompletableFuture
can complete exceptionally
with:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation;
or if a previous Binary message was not sent with isLast == true
CompletableFuture
completes exceptionally.message
- the messageisLast
- true
if this is the last part of the message,
false
otherwiseIllegalArgumentException
- if message
is a malformed (or an incomplete) UTF-16 sequencedefault 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
should not be modified until the returned
CompletableFuture
completes (either normally or exceptionally).
The returned CompletableFuture
can complete exceptionally
with:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation;
or if a previous Binary message was not sent with isLast == true
message
- the messageIllegalArgumentException
- if message
is a malformed (or an incomplete) UTF-16 sequenceCompletableFuture<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:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation;
or if a previous Text message was not sent with isLast == true
message
- the messageisLast
- true
if this is the last part of the message,
false
otherwiseCompletableFuture<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:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation
message
- the messageIllegalArgumentException
- if message.remaining() > 125
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 is 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:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation
message
- the messageIllegalArgumentException
- if message.remaining() > 125
CompletableFuture<WebSocket> sendClose(WebSocket.CloseCode code, CharSequence reason)
Returns a CompletableFuture<WebSocket>
which completes
normally when the message has been sent or completes exceptionally if an
error occurs.
A Close message may consist of a status code and a reason for
closing. The reason must 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.
The returned CompletableFuture
can complete exceptionally
with:
IOException
if an I/O error occurs during this operation
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation
code
- the close codereason
- the reason; can be emptyIllegalArgumentException
- if reason
doesn't have an UTF-8 representation not longer
than 123
bytesCompletableFuture<WebSocket> sendClose()
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
IllegalStateException
if the WebSocket
closes while this operation is in progress;
or if a Close message has been sent already;
or if there is an outstanding send operation
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 connection closes or an error occurs.
A WebSocket
that has just been created, hasn't requested
anything yet. Usually the initial request for messages is done in Listener.onOpen
.
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()
null
if there is noneboolean isClosed()
WebSocket
is closed.
A WebSocket
deemed closed when either the underlying socket
is closed or the closing handshake is completed.
true
if the WebSocket
is closed,
false
otherwisevoid abort() throws IOException
WebSocket
abruptly.
This method closes the underlying TCP connection. 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
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. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-Ubuntu+0-9b147-1