-
- Enclosing interface:
- WebSocket
public static interface WebSocket.ListenerA listener for events and messages on aWebSocket.
Incubating Feature. Will be removed in a future release.Each method of
Listenercorresponds to a type of event or a type of message. TheWebSocketargument of the method is theWebSocketthe event has occurred (the message has been received) on. All methods with the sameWebSocketargument are invoked in a sequential (and happens-before) order, one after another, possibly by different threads.-
onOpen
This method is invoked first. -
onText,onBinary,onPingandonPong
These methods are invoked zero or more times afteronOpen. -
onClose,onError
Only one of these methods is invoked, and that method is invoked last.
Messages received by the
Listenerconform to the WebSocket Protocol, otherwiseonErrorwith aProtocolExceptionis invoked.If a whole message is received, then the corresponding method (
onTextoronBinary) will be invoked withWHOLEmarker. Otherwise the method will be invoked withFIRST, zero or more times withPARTand, finally, withLASTmarkers. If any of the methods above throws an exception,onErroris then invoked with the sameWebSocketand this exception. Exceptions thrown fromonErrororonCloseare ignored.When the method returns, the message is deemed received (in particular, if contained in a
ByteBuffer buffer, the data is deemed received completely regardless of the resultbuffer.hasRemaining()upon the method's return. After this further messages may be received.These invocations begin asynchronous processing which might not end with the invocation. To provide coordination, methods of
Listenerreturn aCompletionStage. TheCompletionStagesignals theWebSocketthat the processing of a message has ended. For convenience, methods may returnnull, which (by convention) means the same as returning an already completed (normally)CompletionStage. If the returnedCompletionStagecompletes exceptionally, thenonErrorwill be invoked with the sameWebSocketand this exception.Control of the message passes to the
Listenerwith the invocation of the method. Control of the message returns to theWebSocketat the earliest of, either returningnullfrom the method, or the completion of theCompletionStagereturned from the method. TheWebSocketdoes not access the message while it's not in its control. TheListenermust not access the message after its control has been returned to theWebSocket.A
WebSocketimplementation never invokesListener's methods withnulls as their arguments.- Since:
- 9
-
-
Method Summary
All Methods Instance Methods Default Methods Modifier and Type Method Description default CompletionStage<?>onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)Receives a Binary message.default CompletionStage<?>onClose(WebSocket webSocket, int statusCode, String reason)Receives a Close message.default voidonError(WebSocket webSocket, Throwable error)Notifies an I/O or protocol error has occurred.default voidonOpen(WebSocket webSocket)Notifies theListenerthat it is connected to the providedWebSocket.default CompletionStage<?>onPing(WebSocket webSocket, ByteBuffer message)Receives a Ping message.default CompletionStage<?>onPong(WebSocket webSocket, ByteBuffer message)Receives a Pong message.default CompletionStage<?>onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)Receives a Text message.
-
-
-
Method Detail
-
onOpen
default void onOpen(WebSocket webSocket)
Notifies theListenerthat it is connected to the providedWebSocket.The
onOpenmethod does not correspond to any message from the WebSocket Protocol. It is a synthetic event and the firstListener's method to be invoked.This method is usually used to make an initial request for messages.
If an exception is thrown from this method then
onErrorwill be invoked with the sameWebSocketand this exception.- Implementation Requirements:
- The default implementation of this method behaves as if:
webSocket.request(1); - Parameters:
webSocket- the WebSocket
-
onText
default CompletionStage<?> onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)
Receives a Text message.The
onTextmethod is invoked zero or more times betweenonOpenand (onCloseoronError).This message may be a partial UTF-16 sequence. However, the concatenation of all messages through the last will be a whole UTF-16 sequence.
If an exception is thrown from this method or the returned
CompletionStagecompletes exceptionally, thenonErrorwill be invoked with the sameWebSocketand this exception.- Implementation Requirements:
- The default implementation of this method behaves as if:
webSocket.request(1); return null; - Implementation Note:
- This implementation passes only complete UTF-16 sequences
to the
onTextmethod. - Parameters:
webSocket- the WebSocketmessage- the messagepart- the part- Returns:
- a
CompletionStagewhich completes when the message processing is done; ornullif already done
-
onBinary
default CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)
Receives a Binary message.The
onBinarymethod is invoked zero or more times betweenonOpenand (onCloseoronError).If an exception is thrown from this method or the returned
CompletionStagecompletes exceptionally, thenonErrorwill be invoked with the sameWebSocketand this exception.- Implementation Requirements:
- The default implementation of this method behaves as if:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocketmessage- the messagepart- the part- Returns:
- a
CompletionStagewhich completes when the message processing is done; ornullif already done
-
onPing
default CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message)
Receives a Ping message.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
WebSockethandles Ping messages by replying with appropriate Pong messages using a strategy of its choice, but within the boundaries of the WebSocket Protocol. TheWebSocketmay invokeonPingafter handling a Ping message, before doing so or in parallel with it. In other words no particular ordering is guaranteed. If an error occurs while implementation handles this Ping message, thenonErrorwill be invoked with this error. For more details on handling Ping messages see RFC 6455 sections 5.5.2. Ping and 5.5.3. Pong.The message will consist of not more than
125bytes:message.remaining() <= 125.The
onPingis invoked zero or more times in betweenonOpenand (onCloseoronError).If an exception is thrown from this method or the returned
CompletionStagecompletes exceptionally, thenonErrorwill be invoked with this exception.- Implementation Requirements:
- The default implementation of this method behaves as if:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocketmessage- the message- Returns:
- a
CompletionStagewhich completes when the message processing is done; ornullif already done
-
onPong
default CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message)
Receives a Pong message.A Pong message may be unsolicited or may be received in response to a previously sent Ping. In the latter case, the contents of the Pong is identical to the originating Ping.
The message will consist of not more than
125bytes:message.remaining() <= 125.The
onPongmethod is invoked zero or more times in betweenonOpenand (onCloseoronError).If an exception is thrown from this method or the returned
CompletionStagecompletes exceptionally, thenonErrorwill be invoked with this exception.- Implementation Requirements:
- The default implementation of this method behaves as if:
webSocket.request(1); return null; - Parameters:
webSocket- the WebSocketmessage- the message- Returns:
- a
CompletionStagewhich completes when the message processing is done; ornullif already done
-
onClose
default CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)
Receives a Close message.A Close message consists of a status code and a reason for closing. The status code is an integer in the range
1000 <= code <= 65535. Thereasonis a short string that has an UTF-8 representation not longer than123bytes. For more details on Close message, status codes and reason see RFC 6455 sections 5.5.1. Close and 7.4. Status Codes.After the returned
CompletionStagehas completed (normally or exceptionally), theWebSocketcompletes the closing handshake by replying with an appropriate Close message.This implementation replies with a Close message that has the same code this message has and an empty reason.
onCloseis the last invocation on theListener. It is invoked at most once, but afteronOpen. If an exception is thrown from this method, it is ignored.The
WebSocketwill close at the earliest of completion of the returnedCompletionStageor sending a Close message. In particular, if a Close message has been sent before, then this invocation completes the closing handshake and by the time this method is invoked, theWebSocketwill have been closed.- Implementation Requirements:
- The default implementation of this method behaves as if:
return null; - Parameters:
webSocket- the WebSocketstatusCode- the status codereason- the reason- Returns:
- a
CompletionStagewhich completes when theWebSocketcan be closed; ornullif it can be closed immediately - See Also:
WebSocket.NORMAL_CLOSURE
-
onError
default void onError(WebSocket webSocket, Throwable error)
Notifies an I/O or protocol error has occurred.The
onErrormethod does not correspond to any message from the WebSocket Protocol. It is a synthetic event and the lastListener's method to be invoked. It is invoked at most once but afteronOpen. If an exception is thrown from this method, it is ignored.Note that the WebSocket Protocol requires some errors occur in the incoming destination must be fatal to the connection. In such cases the implementation takes care of Failing the WebSocket Connection: by the time
onErroris invoked, theWebSocketwill have been closed. Any outstanding or subsequent send operation will complete exceptionally with anIOException. For more details on Failing the WebSocket Connection see RFC 6455 section 7.1.7. Fail the WebSocket Connection.- API Note:
- Errors associated with sending messages are reported to the
CompletableFuturessendXmethods return, rather than to this this method. - Implementation Requirements:
- The default implementation of this method does nothing.
- Parameters:
webSocket- the WebSocketerror- the error
-
-