java.net.http

Interface WebSocket

public interface WebSocket

A WebSocket client conforming to RFC 6455.

A WebSocket provides a full-duplex message exchange. Once a WebSocket is created, it's connected and is ready to exchange messages. To create a WebSocket a builder is used. When the WebSocket is no longer needed it should 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.

Message exchange is asynchronous. Each of send methods begins the operation and returns a CompletableFuture which completes when the message has been sent. Received messages are delivered to the Listener.

Messages are delivered 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 delivered 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 delivered.

If contained in a ByteBuffer, message 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 (or any inner one) will cause a NullPointerException to be thrown.

Since:

9

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	WebSocket.Builder A builder for creating WebSocket instances.
static interface	WebSocket.CloseCode A WebSocket close status code.
static interface	WebSocket.Listener A listener for events on the WebSocket.
static class	WebSocket.MessagePart A marker for the position of a message in a sequence of messages delivered to the WebSocket.Listener.
static interface	WebSocket.Text A character sequence that provides access to the characters UTF-8 decoded from a message in a ByteBuffer.

Method Summary

Modifier and Type	Method and Description
void	abort() Closes the WebSocket abruptly.
java.lang.String	getSubprotocol() Returns a subprotocol in use.
boolean	isClosed() Tells whether the WebSocket is closed.
java.util.concurrent.CompletableFuture<java.lang.Void>	ping(java.nio.ByteBuffer message) Sends a Ping message.
java.util.concurrent.CompletableFuture<java.lang.Void>	pong(java.nio.ByteBuffer message) Sends a Pong message.
void	request(long n) Requests n more messages to be delivered to the Listener.
default java.util.concurrent.CompletableFuture<java.lang.Void>	sendBinary(byte[] message, boolean isLast) Sends a Binary message with bytes from the given byte[].
java.util.concurrent.CompletableFuture<java.lang.Void>	sendBinary(java.nio.ByteBuffer message, boolean isLast) Sends a Binary message with bytes from the given ByteBuffer.
java.util.concurrent.CompletableFuture<java.lang.Void>	sendClose() Sends an empty Close message.
java.util.concurrent.CompletableFuture<java.lang.Void>	sendClose(WebSocket.CloseCode code, java.lang.CharSequence reason) Sends a Close message with the given close code and the reason.
java.util.concurrent.CompletableFuture<java.lang.Void>	sendText(java.nio.ByteBuffer message, boolean isLast) Sends a Text message with bytes from the given ByteBuffer.
default java.util.concurrent.CompletableFuture<java.lang.Void>	sendText(java.lang.CharSequence message) Sends a whole Text message with characters from the given CharSequence.
java.util.concurrent.CompletableFuture<java.lang.Void>	sendText(java.lang.CharSequence message, boolean isLast) Sends a Text message with characters from the given CharSequence.
java.util.concurrent.CompletableFuture<java.lang.Void>	sendText(java.util.stream.Stream<? extends java.lang.CharSequence> message) Sends a whole Text message with characters from CharacterSequences provided by the given Stream.

Method Detail

sendText

java.util.concurrent.CompletableFuture<java.lang.Void> sendText(java.nio.ByteBuffer message,
                                                                boolean isLast)

Sends a Text message with bytes from the given ByteBuffer.

Returns immediately with a CompletableFuture<Void> which completes normally when the message has been sent, or completes exceptionally if an error occurs.

This message may be a partial UTF-8 sequence. However, the concatenation of all messages through the last must be a whole UTF-8 sequence.

The ByteBuffer 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; or the WebSocket closes while this operation is in progress; or the message is a malformed UTF-8 sequence

Parameters:

message - the message

isLast - true if this is the final part of the message, false otherwise

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been sent already

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Binary message was not sent with isLast == true

sendText

java.util.concurrent.CompletableFuture<java.lang.Void> sendText(java.lang.CharSequence message,
                                                                boolean isLast)

Sends a Text message with characters from the given CharSequence.

Returns immediately with a CompletableFuture<Void> which completes normally when the message has been sent, or completes exceptionally if an error occurs.

This message may be a partial UTF-16 sequence. However, the concatenation of all messages through the last must be a whole UTF-16 sequence.

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; or the WebSocket closes while this operation is in progress; or the message is a malformed UTF-16 sequence

Parameters:

message - the message

isLast - true if this is the final part of the message false otherwise

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Binary message was not sent with isLast == true

sendText

default java.util.concurrent.CompletableFuture<java.lang.Void> sendText(java.lang.CharSequence message)

Sends a whole Text message with characters from the given CharSequence.

This is a convenience method. For the general case use sendText(CharSequence, boolean).

Returns immediately with a CompletableFuture<Void> 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; or the WebSocket closes while this operation is in progress; or the message is a malformed UTF-16 sequence

Parameters:

message - the message

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Binary message was not sent with isLast == true

sendText

java.util.concurrent.CompletableFuture<java.lang.Void> sendText(java.util.stream.Stream<? extends java.lang.CharSequence> message)

Sends a whole Text message with characters from CharacterSequences provided by the given Stream.

This is a convenience method. For the general case use sendText(CharSequence, boolean).

Returns immediately with a CompletableFuture<Void> 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; or the WebSocket closes while this operation is in progress; or the message is a malformed UTF-16 sequence

Parameters:

message - the message

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Binary message was not sent with isLast == true

sendBinary

java.util.concurrent.CompletableFuture<java.lang.Void> sendBinary(java.nio.ByteBuffer message,
                                                                  boolean isLast)

Sends a Binary message with bytes from the given ByteBuffer.

Returns immediately with a CompletableFuture<Void> 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 closes while this operation is in progress

Parameters:

message - the message

isLast - true if this is the final part of the message, false otherwise

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Text message was not sent with isLast == true

sendBinary

default java.util.concurrent.CompletableFuture<java.lang.Void> sendBinary(byte[] message,
                                                                          boolean isLast)

Sends a Binary message with bytes from the given byte[].

Returns immediately with a CompletableFuture<Void> which completes normally when the message has been sent, or completes exceptionally if an error occurs.

Is equivalent to:

     sendBinary(ByteBuffer.wrap(message), isLast)
 

The returned CompletableFuture can complete exceptionally with:

• IOException if an I/O error occurs during this operation or the WebSocket closes while this operation is in progress

Parameters:

message - the message

isLast - true if this is the final part of the message, false otherwise

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalStateException - if a previous Text message was not sent with isLast == true

ping

java.util.concurrent.CompletableFuture<java.lang.Void> ping(java.nio.ByteBuffer message)

Sends a Ping message.

Returns immediately with a CompletableFuture<Void> 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 or the WebSocket closes while this operation is in progress

Parameters:

message - the message

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalArgumentException - if message.remaining() > 125

pong

java.util.concurrent.CompletableFuture<java.lang.Void> pong(java.nio.ByteBuffer message)

Sends a Pong message.

Returns immediately with a CompletableFuture<Void> 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 or the WebSocket closes while this operation is in progress

Parameters:

message - the message

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalArgumentException - if message.remaining() > 125

sendClose

java.util.concurrent.CompletableFuture<java.lang.Void> sendClose(WebSocket.CloseCode code,
                                                                 java.lang.CharSequence reason)

Sends a Close message with the given close code and the reason.

Returns immediately with a CompletableFuture<Void> 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 or the WebSocket closes while this operation is in progress

Parameters:

code - the close code

reason - the reason; can be empty

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

java.lang.IllegalArgumentException - if the reason doesn't have a valid UTF-8 representation not longer than 123 bytes

sendClose

java.util.concurrent.CompletableFuture<java.lang.Void> sendClose()

Sends an empty Close message.

Returns immediately with a CompletableFuture<Void> 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 closes while this operation is in progress

Returns:

a CompletableFuture of Void

Throws:

java.lang.IllegalStateException - if the WebSocket is closed

java.lang.IllegalStateException - if a Close message has been already sent

java.lang.IllegalStateException - if there is an outstanding send operation

request

void request(long n)

Requests n more messages to be delivered to 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 delivered, and the server sends more, then these messages are queued.

Parameters:

n - the number of messages

Throws:

java.lang.IllegalArgumentException - if n < 0

API Note:

This method does not distinguish between partial and whole messages, because it's not known beforehand how a message will be delivered.

Implementation Note:

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.

getSubprotocol

java.lang.String getSubprotocol()

Returns a subprotocol in use.

Returns:

a subprotocol, or null if there is none

isClosed

boolean isClosed()

Tells whether the WebSocket is closed.

A WebSocket deemed closed when either the underlying socket is closed or the closing handshake is completed.

Returns:

true if the WebSocket is closed, false otherwise

abort

void abort()
    throws java.io.IOException

Closes the WebSocket abruptly.

This method closes the underlying TCP connection. If the WebSocket is already closed then invoking this method has no effect.

Throws:

java.io.IOException - if an I/O error occurs