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. Or to close abruptly, abort()
is called. Once
closed it remains closed, 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
.
All message exchange is run by the threads belonging to the executor service of WebSocket
's HttpClient
.
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 and 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 for partial message
receiving. |
Modifier and Type | Method and 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 . |
long |
request(long n)
Requests
n more messages to be received by the Listener . |
default CompletableFuture<WebSocket> |
sendBinary(byte[] message,
boolean isLast)
Sends a Binary message with bytes from the given
byte[] . |
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 . |
CompletableFuture<WebSocket> |
sendText(Stream<? extends CharSequence> message)
Sends a whole Text message with characters from
CharacterSequence s provided by the given Stream . |
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 final 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> sendText(Stream<? extends CharSequence> message)
CharacterSequence
s provided by the given Stream
.
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.
Streamed character sequences 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 final part of the message,
false
otherwisedefault CompletableFuture<WebSocket> sendBinary(byte[] message, boolean isLast)
byte[]
.
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
sendBinary(ByteBuffer.wrap(message), isLast)
message
- the messageisLast
- true
if this is the final 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 close code and a reason for closing.
The reason must have a valid 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
long request(long n)
n
more messages to be received by the Listener
.
The actual number might be fewer if either of the endpoints decide to close the connection before that 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 all requested messages have been received, and the server sends more,
then these messages are queued.
If a server sends more messages than requested, the 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. All rights reserved.
DRAFT 9-internal+0-2016-06-25-232344.buildd.src