bayou.websocket

Interface WebSocketChannel

public interface WebSocketChannel

WebSocket channel for reading and writing messages.

To read the next WebSocketMessage from the the peer, call readMessage(), or convenience methods readText(int), readBinary(int). These actions will fail with WebSocketClose if the inbound is gracefully closed by the peer.

To write a WebSocketMessage to the peer, call writeMessage(WebSocketMessage), or convenience methods writeText(CharSequence), writeBinary(byte[]).

To gracefully close the outbound, call writeClose().

The channel must be eventually closed by calling close().

Method Summary

Abstract Methods
Async<WebSocketMessage>	readMessage() Read the next message from the peer.
Async<Long>	writeMessage(WebSocketMessage message) Write a message to the peer.
Async<Void>	writeClose() Close the outbound gracefully.
Async<Void>	close() Close the channel.
Default Methods
Async<String>	readText(int maxChars) Read the next text message as one String.
Async<ByteBuffer>	readBinary(int maxBytes) Read the next binary message into one ByteBuffer.
Async<Long>	writeText(CharSequence chars) Write a text message to the peer.
Async<Long>	writeBinary(byte[] bytes) Write a binary message to the peer.

Method Detail

readMessage

Async<WebSocketMessage> readMessage()

Read the next message from the peer.

This action will succeed when the next message arrives. The application must read the message till EOF, or close the message (regardless of EOF), before it can call readMessage() again.

This action will fail with WebSocketClose (a subtype of End) if the inbound is gracefully closed by the peer.

readText

default Async<String> readText(int maxChars)

Read the next text message as one String.

The next message must be a Text message. If it's a Binary message instead, this action fails with WebSocketException.

Parameters:

maxChars - maximum chars expected in the message. If exceeded, this action fails with OverLimitException.

readBinary

default Async<ByteBuffer> readBinary(int maxBytes)

Read the next binary message into one ByteBuffer.

The next message must be a Binary message. If it's a Text message instead, this action fails with WebSocketException.

Parameters:

maxBytes - maximum bytes expected in the message. If exceeded, this action fails with OverLimitException.

writeMessage

Async<Long> writeMessage(WebSocketMessage message)

Write a message to the peer.

This action succeeds after the message is written; the result is the total bytes in the message (not including framing bytes).

This method should not be called after writeClose() is called.

It's not necessary to wait for a writeMessage() action to complete before writing the next message. The outbound messages will be queued. However, the application should wait for the last writeMessage() action (or the writeClose() action if it's called) to complete before calling close() to ensure outbound data are reliably delivered.

If this action fails (e.g. because the action is cancelled, or message.read() fails), the outbound is likely corrupt, the channel should be by closed by close().

writeText

default Async<Long> writeText(CharSequence chars)

Write a text message to the peer.

This method is equivalent to writeMessage(WebSocketMessage.text(chars)).

writeBinary

default Async<Long> writeBinary(byte[] bytes)

Write a binary message to the peer.

This method is equivalent to writeMessage(WebSocketMessage.binary(bytes)).

writeClose

Async<Void> writeClose()

Close the outbound gracefully.

A Close-Frame will be sent to the peer (after queued outbound messages are sent).

This method can be called at most once.

close

Async<Void> close()

Close the channel.

This method frees resources associated with this channel, e.g. the underlying TCP connection.

This method does *not* perform Close-Frame exchange; if the application wants to, it can do that through readMessage() and writeClose().

This method can be called multiple times; only the first call is effective.