Interface WebSocket.Listener
- Enclosing interface:
WebSocket
WebSocket.
A WebSocket invokes methods of the associated listener
passing itself as an argument. These methods are invoked in a thread-safe
manner, such that the next invocation may start only after the previous
one has finished.
When data has been received, the WebSocket invokes a receive
method. Methods onText, onBinary, onPing and
onPong must return a CompletionStage that completes once
the message has been received by the listener. If a listener's method
returns null rather than a CompletionStage,
WebSocket will behave as if the listener returned a
CompletionStage that is already completed normally.
An IOException raised in WebSocket will result in an
invocation of onError with that exception (if the input is not
closed). Unless otherwise stated if the listener's method throws an
exception or a CompletionStage returned from a method completes
exceptionally, the WebSocket will invoke onError with this
exception.
- API Note:
- The strict sequential order of invocations from
WebSockettoListenermeans, in particular, that theListener's methods are treated as non-reentrant. This means thatListenerimplementations do not need to be concerned with possible recursion or the order in which they invokeWebSocket.requestin relation to their processing logic.Careful attention may be required if a listener is associated with more than a single
WebSocket. In this case invocations related to different instances ofWebSocketmay not be ordered and may even happen concurrently.CompletionStages returned from the receive methods have nothing to do with the counter of invocations. Namely, aCompletionStagedoes not have to be completed in order to receive more invocations of the listener's methods. Here is an example of a listener that requests invocations, one at a time, until a complete message has been accumulated, then processes the result, and completes theCompletionStage:WebSocket.Listener listener = new WebSocket.Listener() { List<CharSequence> parts = new ArrayList<>(); CompletableFuture<?> accumulatedMessage = new CompletableFuture<>(); public CompletionStage<?> onText(WebSocket webSocket, CharSequence message, boolean last) { parts.add(message); webSocket.request(1); if (last) { processWholeText(parts); parts = new ArrayList<>(); accumulatedMessage.complete(null); CompletionStage<?> cf = accumulatedMessage; accumulatedMessage = new CompletableFuture<>(); return cf; } return accumulatedMessage; } }; - Since:
- 11
-
Method Summary
Modifier and TypeMethodDescriptiondefault CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer data, boolean last) A binary data has been received.default CompletionStage<?> Receives a Close message indicating the WebSocket's input has been closed.default voidAn error has occurred.default voidAWebSockethas been connected.default CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message) A Ping message has been received.default CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message) A Pong message has been received.default CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) A textual data has been received.
-
Method Details
-
onOpen
AWebSockethas been connected.This is the initial invocation and it is made once. It is typically used to make a request for more invocations.
- Implementation Requirements:
- The default implementation is equivalent to:
webSocket.request(1); - Parameters:
webSocket- the WebSocket that has been connected
-
onText
A textual data has been received.Return a
CompletionStagewhich will be used by theWebSocketas an indication it may reclaim theCharSequence. Do not access theCharSequenceafter thisCompletionStagehas completed.- Implementation Requirements:
- The default implementation is equivalent to:
webSocket.request(1); return null; - Implementation Note:
- The
datais always a legal UTF-16 sequence. - Parameters:
webSocket- the WebSocket on which the data has been receiveddata- the datalast- whether this invocation completes the message- Returns:
- a
CompletionStagewhich completes when theCharSequencemay be reclaimed; ornullif it may be reclaimed immediately
-
onBinary
A binary data has been received.This data is located in bytes from the buffer's position to its limit.
Return a
CompletionStagewhich will be used by theWebSocketas an indication it may reclaim theByteBuffer. Do not access theByteBufferafter thisCompletionStagehas completed.- Implementation Requirements:
- The default implementation is equivalent to:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocket on which the data has been receiveddata- the datalast- whether this invocation completes the message- Returns:
- a
CompletionStagewhich completes when theByteBuffermay be reclaimed; ornullif it may be reclaimed immediately
-
onPing
A Ping message has been received.As guaranteed by the WebSocket Protocol, the message consists of not more than
125bytes. These bytes are located from the buffer's position to its limit.Given that the WebSocket implementation will automatically send a reciprocal pong when a ping is received, it is rarely required to send a pong message explicitly when a ping is received.
Return a
CompletionStagewhich will be used by theWebSocketas a signal it may reclaim theByteBuffer. Do not access theByteBufferafter thisCompletionStagehas completed.- Implementation Requirements:
- The default implementation is equivalent to:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocket on which the message has been receivedmessage- the message- Returns:
- a
CompletionStagewhich completes when theByteBuffermay be reclaimed; ornullif it may be reclaimed immediately
-
onPong
A Pong message has been received.As guaranteed by the WebSocket Protocol, the message consists of not more than
125bytes. These bytes are located from the buffer's position to its limit.Return a
CompletionStagewhich will be used by theWebSocketas a signal it may reclaim theByteBuffer. Do not access theByteBufferafter thisCompletionStagehas completed.- Implementation Requirements:
- The default implementation is equivalent to:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocket on which the message has been receivedmessage- the message- Returns:
- a
CompletionStagewhich completes when theByteBuffermay be reclaimed; ornullif it may be reclaimed immediately
-
onClose
Receives a Close message indicating the WebSocket's input has been closed.This is the last invocation from the specified
WebSocket. By the time this invocation begins the WebSocket's input will have been closed.A Close message consists of a status code and a reason for closing. The status code is an integer from the range
1000 <= code <= 65535. Thereasonis a string which has a UTF-8 representation not longer than123bytes.If the WebSocket's output is not already closed, the
CompletionStagereturned by this method will be used as an indication that the WebSocket's output may be closed. The WebSocket will close its output at the earliest of completion of the returnedCompletionStageor invoking either of thesendCloseorabortmethods.- API Note:
- Returning a
CompletionStagethat never completes, effectively disables the reciprocating closure of the output.To specify a custom closure code or reason code the
sendClosemethod may be invoked from inside theonCloseinvocation:public CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason) { webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON); return new CompletableFuture<Void>(); } - Implementation Requirements:
- The default implementation of this method returns
null, indicating that the output should be closed immediately. - Parameters:
webSocket- the WebSocket on which the message has been receivedstatusCode- the status codereason- the reason- Returns:
- a
CompletionStagewhich completes when theWebSocketmay be closed; ornullif it may be closed immediately
-
onError
An error has occurred.This is the last invocation from the specified WebSocket. By the time this invocation begins both the WebSocket's input and output will have been closed. A WebSocket may invoke this method on the associated listener at any time after it has invoked
onOpen, regardless of whether or not any invocations have been requested from the WebSocket.If an exception is thrown from this method, resulting behavior is undefined.
- Parameters:
webSocket- the WebSocket on which the error has occurrederror- the error
-