-
public interface WebSocket
A WebSocket client.
Incubating Feature. Will be removed in a future release.To create a
WebSocket
use theHttpClient.newWebSocketBuilder()
method. To close aWebSocket
use one of thesendClose
orabort
methods.WebSocket messages are sent through a
WebSocket
and received through theWebSocket
'sListener
. Messages can be sent until the output is closed, and received until the input is closed. AWebSocket
whose output and input are both closed may be considered itself closed. To check these states useisOutputClosed()
andisInputClosed()
.Methods that send messages return
CompletableFuture
which completes normally if the message is sent or completes exceptionally if an error occurs.To receive a message, first request it. If
n
messages are requested, the listener will receive up ton
more invocations of the designated methods from theWebSocket
. To request messages userequest(long)
. Request is an additive operation, that isrequest(n)
followed byrequest(m)
is equivalent torequest(n + m)
.When sending or receiving a message in parts, a whole message is transferred as a sequence of one or more invocations where the last invocation is identified via an additional method argument.
Unless otherwise stated,
null
arguments will cause methods ofWebSocket
to throwNullPointerException
, similarly,WebSocket
will not passnull
arguments to methods ofListener
.- Implementation Requirements:
- Methods of
WebSocket
are failure-atomic in respect toNullPointerException
,IllegalArgumentException
andIllegalStateException
. That is, if a method throws said exception, or a returnedCompletableFuture
completes exceptionally with said exception, theWebSocket
will behave as if the method has not been invoked at all.A
WebSocket
invokes methods of its listener in a thread-safe manner.WebSocket
handles Ping and Close messages automatically (as per RFC 6455) by replying with Pong and Close messages respectively. If the listener receives Ping or Close messages, no mandatory actions from the listener are required. - Since:
- 9
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
WebSocket.Builder
A builder for creatingWebSocket
instances.static interface
WebSocket.Listener
The receiving interface ofWebSocket
.static class
WebSocket.MessagePart
A marker used byWebSocket.Listener
for identifying partial messages.
-
Field Summary
Fields Modifier and Type Field Description 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.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
abort()
Closes thisWebSocket
abruptly.String
getSubprotocol()
Returns the subprotocol for thisWebSocket
.boolean
isInputClosed()
Tells whether or not thisWebSocket
is permanently closed for receiving messages.boolean
isOutputClosed()
Tells whether or not thisWebSocket
is permanently closed for sending messages.void
request(long n)
Requestsn
more messages from thisWebSocket
.CompletableFuture<WebSocket>
sendBinary(ByteBuffer message, boolean isLast)
Sends a Binary message with bytes from the givenByteBuffer
.CompletableFuture<WebSocket>
sendClose(int statusCode, String reason)
Sends a Close message with the given status code and the reason, initiating an orderly closure.CompletableFuture<WebSocket>
sendPing(ByteBuffer message)
Sends a Ping message with bytes from the givenByteBuffer
.CompletableFuture<WebSocket>
sendPong(ByteBuffer message)
Sends a Pong message with bytes from the givenByteBuffer
.CompletableFuture<WebSocket>
sendText(CharSequence message, boolean isLast)
Sends a Text message with characters from the givenCharSequence
.
-
-
-
Method Detail
-
sendText
CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast)
Sends a Text message with characters from the givenCharSequence
.To send a Text message invoke this method only after the previous Text or Binary message has been sent. The character sequence must not be modified until the
CompletableFuture
returned from this method has completed.A
CompletableFuture
returned from this method can complete exceptionally with:-
IllegalArgumentException
- ifmessage
is a malformed UTF-16 sequence -
IllegalStateException
- ifsendClose
has been invoked or if the previous message has not been sent yet or if a previous Binary message was sent withisLast == false
-
IOException
- if an I/O error occurs
- Implementation Note:
- If a partial UTF-16 sequence is passed to this method, a
CompletableFuture
returned will complete exceptionally withIOException
. - Parameters:
message
- the messageisLast
-true
if this is the last part of the message,false
otherwise- Returns:
- a
CompletableFuture
that completes, with thisWebSocket
, when the message has been sent
-
-
sendBinary
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast)
Sends a Binary message with bytes from the givenByteBuffer
.To send a Binary message invoke this method only after the previous Text or Binary message has been sent. The message consists of bytes from the buffer's position to its limit. Upon normal completion of a
CompletableFuture
returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.The
CompletableFuture
returned from this method can complete exceptionally with:-
IllegalStateException
- ifsendClose
has been invoked or if the previous message has not been sent yet or if a previous Text message was sent withisLast == false
-
IOException
- if an I/O error occurs
- Parameters:
message
- the messageisLast
-true
if this is the last part of the message,false
otherwise- Returns:
- a
CompletableFuture
that completes, with thisWebSocket
, when the message has been sent
-
-
sendPing
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
Sends a Ping message with bytes from the givenByteBuffer
.The message consists of not more than
125
bytes from the buffer's position to its limit. Upon normal completion of aCompletableFuture
returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.The
CompletableFuture
returned from this method can complete exceptionally with:-
IllegalArgumentException
- if the message is too long -
IllegalStateException
- ifsendClose
has been invoked -
IOException
- if an I/O error occurs
- Parameters:
message
- the message- Returns:
- a
CompletableFuture
that completes, with thisWebSocket
, when the Ping message has been sent
-
-
sendPong
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
Sends a Pong message with bytes from the givenByteBuffer
.The message consists of not more than
125
bytes from the buffer's position to its limit. Upon normal completion of aCompletableFuture
returned from this method the buffer will have no remaining bytes. The buffer must not be accessed until after that.The
CompletableFuture
returned from this method can complete exceptionally with:-
IllegalArgumentException
- if the message is too long -
IllegalStateException
- ifsendClose
has been invoked -
IOException
- if an I/O error occurs
- Parameters:
message
- the message- Returns:
- a
CompletableFuture
that completes, with thisWebSocket
, when the Pong message has been sent
-
-
sendClose
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
Sends a Close message with the given status code and the reason, initiating an orderly closure.When this method returns the output will have been closed.
The
statusCode
is an integer from the range1000 <= code <= 4999
. Status codes1002
,1003
,1006
,1007
,1009
,1010
,1012
,1013
and1015
are illegal. Behaviour in respect to other status codes is implementation-specific. Thereason
is a string that has an UTF-8 representation not longer than123
bytes.Use the provided integer constant
NORMAL_CLOSURE
as a status code and an empty string as a reason in a typical case.A
CompletableFuture
returned from this method can complete exceptionally with:-
IllegalArgumentException
- ifstatusCode
orreason
are illegal -
IOException
- if an I/O error occurs
- Implementation Requirements:
- An endpoint sending a Close message might not receive a
complementing Close message in a timely manner for a variety of reasons.
The
WebSocket
implementation is responsible for providing a closure mechanism that guarantees that oncesendClose
method has been invoked theWebSocket
will close regardless of whether or not a Close frame has been received and without further intervention from the user of this API. MethodsendClose
is designed to be, possibly, the last call from the user of this API. - Parameters:
statusCode
- the status codereason
- the reason- Returns:
- a
CompletableFuture
that completes, with thisWebSocket
, when the Close message has been sent
-
-
request
void request(long n)
Requestsn
more messages from thisWebSocket
.This
WebSocket
will invoke its listener'sonText
,onBinary
,onPing
,onPong
oronClose
methods up ton
more times.This method may be invoked at any time.
- Parameters:
n
- the number of messages requested- Throws:
IllegalArgumentException
- ifn <= 0
-
getSubprotocol
String getSubprotocol()
Returns the subprotocol for thisWebSocket
.This method may be invoked at any time.
- Returns:
- the subprotocol for this
WebSocket
, or an emptyString
if there's no subprotocol
-
isOutputClosed
boolean isOutputClosed()
Tells whether or not thisWebSocket
is permanently closed for sending messages.If this method returns
true
, subsequent invocations will also returntrue
. This method may be invoked at any time.- Returns:
true
if closed,false
otherwise
-
isInputClosed
boolean isInputClosed()
Tells whether or not thisWebSocket
is permanently closed for receiving messages.If this method returns
true
, subsequent invocations will also returntrue
. This method may be invoked at any time.- Returns:
true
if closed,false
otherwise
-
abort
void abort()
Closes thisWebSocket
abruptly.When this method returns both the input and output will have been closed. This method may be invoked at any time. Subsequent invocations have no effect.
- API Note:
- Depending on its implementation, the state (for example, whether
or not a message is being transferred at the moment) and possible errors
while releasing associated resources, this
WebSocket
may invoke its listener'sonError
.
-
-