Module jdk.incubator.httpclient

Package jdk.incubator.http

Interface WebSocket

public interface WebSocket

A WebSocket client conforming to RFC 6455.
Incubating Feature. Will be removed in a future release.

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.

Implementation Note:

This implementation's methods do not block before returning a CompletableFuture.

Since:

9

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

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.

Method Summary

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.

Field Detail

NORMAL_CLOSURE

static final 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.

See Also:

sendClose(int, String), WebSocket.Listener.onClose(WebSocket, int, String), Constant Field Values

CLOSED_ABNORMALLY

static final 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.

See Also:

WebSocket.Listener.onClose(WebSocket, int, String), abort(), Constant Field Values

Method Detail

sendText

CompletableFuture<WebSocket> sendText(CharSequence message,
                                      boolean isLast)

Sends a Text message with characters from the given 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;

Implementation Note:

This implementation does not accept partial UTF-16 sequences. In case such a sequence is passed, a returned CompletableFuture completes exceptionally with IOException.

Parameters:

message - the message

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

Returns:

a CompletableFuture with this WebSocket

sendText

default CompletableFuture<WebSocket> sendText(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 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;

Parameters:

message - the message

Returns:

a CompletableFuture with this WebSocket

sendBinary

CompletableFuture<WebSocket> sendBinary(ByteBuffer message,
                                        boolean isLast)

Sends a Binary message with bytes from the given 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

Parameters:

message - the message

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

Returns:

a CompletableFuture with this WebSocket

sendPing

CompletableFuture<WebSocket> sendPing(ByteBuffer message)

Sends a Ping message with bytes from the given ByteBuffer.

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

Parameters:

message - the message

Returns:

a CompletableFuture with this WebSocket

sendPong

CompletableFuture<WebSocket> sendPong(ByteBuffer message)

Sends a Pong message with bytes from the given ByteBuffer.

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

Parameters:

message - the message

Returns:

a CompletableFuture with this WebSocket

sendClose

CompletableFuture<WebSocket> sendClose(int statusCode,
                                       String reason)

Sends a Close message with the given status code and the 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.

Parameters:

statusCode - the status code

reason - the reason

Returns:

a CompletableFuture with this WebSocket

See Also:

sendClose()

sendClose

CompletableFuture<WebSocket> sendClose()

Sends an empty Close message.

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.

Returns:

a CompletableFuture with this WebSocket

See Also:

sendClose(int, String)

request

void request(long n)

Allows 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.

Implementation Note:

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

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.

Parameters:

n - the number of messages

Throws:

IllegalArgumentException - if n < 0

getSubprotocol

String getSubprotocol()

Returns a subprotocol which has been chosen for this WebSocket.

Returns:

a subprotocol, or an empty String if there is none

isClosed

boolean isClosed()

Tells whether the WebSocket is closed.

When a WebSocket is closed no further messages can be sent or received.

Returns:

true if the WebSocket is closed, false otherwise

abort

void abort()
    throws IOException

Closes the 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.

Throws:

IOException - if an I/O error occurs