-
- Enclosing interface:
- WebSocket
public static interface WebSocket.Listener
一个WebSocket
事件和消息的WebSocket
。
Incubating Feature.将在以后的版本中删除。Listener
每个方法对应于事件的类型或消息的类型。 该方法的WebSocket
参数是WebSocket
事件已发生(已收到消息)。 具有相同的WebSocket
参数的所有方法都以顺序(和happens-before )顺序相继调用,可能由不同的线程调用。-
onOpen
首先调用此方法。 -
onText
,onBinary
,onPing
和onPong
这些方法在onOpen
之后被调用了零次或多次。 -
onClose
,onError
只调用其中一种方法,最后调用该方法。
Listener
接收到的Listener
符合WebSocket协议,否则将调用onError
与ProtocolException
。如果收到整条消息,则将使用
WHOLE
标记来调用相应的方法(onText
或onBinary
)。 否则将使用FIRST
调用该方法,或多次使用PART
,最后使用LAST
标记。 如果上述任何方法引发异常,则onError
被调用与相同的WebSocket
和此异常。 从onError
或onClose
抛出的异常被忽略。当该方法返回时,该消息被认为是接收的(特别是如果包含在
ByteBuffer buffer
,则无论方法返回时是否完成buffer.hasRemaining()
的结果,数据被认为完全被接收。这些调用开始异步处理,这可能不会以调用结束。 提供协调,方法
Listener
返回一个CompletionStage
。CompletionStage
表示WebSocket
处理消息已经结束。 为方便起见,方法可能会返回null
,按照惯例,这意味着返回一个已经完成的(通常的)CompletionStage
。 如果返回CompletionStage
格外完成,然后onError
将用相同的调用WebSocket
与此异常。该消息的控制传递给
Listener
与该方法的调用。 消息的控制最早返回到WebSocket
,从方法返回null
,或完成从方法返回的CompletionStage
。WebSocket
不能访问该消息,而不在其控制。Listener
不能访问该消息后其控件已被返回到WebSocket
。A
WebSocket
实现从不调用Listener
的方法,其中null
作为其参数。- 从以下版本开始:
- 9
-
-
方法摘要
所有方法 接口方法 Default Methods Modifier and Type 方法 描述 default CompletionStage<?>
onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)
接收二进制消息。default CompletionStage<?>
onClose(WebSocket webSocket, int statusCode, String reason)
接收到一条关闭消息。default void
onError(WebSocket webSocket, Throwable error)
通知发生I / O或协议错误。default void
onOpen(WebSocket webSocket)
通知Listener
它连接到提供的WebSocket
。default CompletionStage<?>
onPing(WebSocket webSocket, ByteBuffer message)
接收Ping消息。default CompletionStage<?>
onPong(WebSocket webSocket, ByteBuffer message)
收到乒乓消息。default CompletionStage<?>
onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)
接收短信。
-
-
-
方法详细信息
-
onOpen
default void onOpen(WebSocket webSocket)
通知Listener
它连接到提供的WebSocket
。onOpen
方法与WebSocket协议的任何消息不对应。 这是一个合成事件和第一个被调用的Listener
的方法。此方法通常用于为邮件创建初始的request 。
如果一个异常是从此方法抛出,则
onError
将使用相同的调用WebSocket
与此异常。- 实现要求:
-
此方法的默认实现方式如下:
webSocket.request(1);
- 参数
-
webSocket
- WebSocket
-
onText
default CompletionStage<?> onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)
接收短信。onText
方法在onOpen
和(onClose
或onError
)之间调用零次或onError
。该消息可以是部分UTF-16序列。 然而,所有消息通过最后的连接将是一个完整的UTF-16序列。
如果一个异常是从此方法抛出或返回
CompletionStage
完成分外,然后onError
将用相同的调用WebSocket
与此异常。- 实现要求:
-
此方法的默认实现方式如下:
webSocket.request(1); return null;
- Implementation Note:
-
此实现只将完整的UTF-16序列传递到
onText
方法。 - 参数
-
webSocket
- WebSocket -
message
- 消息 -
part
- 的部分 - 结果
-
一个完成消息处理的
CompletionStage
; 或null
如果已经完成
-
onBinary
default CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)
接收二进制消息。onBinary
方法在onOpen
和(onClose
或onError
)之间调用零次或onError
。如果一个异常是从此方法抛出或返回
CompletionStage
完成分外,然后onError
将用相同的调用WebSocket
与此异常。- 实现要求:
-
此方法的默认实现方式如下:
webSocket.request(1); return null;
- 参数
-
webSocket
- WebSocket -
message
- 消息 -
part
- 的部分 - 结果
-
一个完成消息处理的
CompletionStage
; 或null
如果已经完成
-
onPing
default CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message)
接收Ping消息。Ping消息可以由客户端或服务器发送或接收。 它可以用作keepalive或作为验证远程端点仍然响应的手段。
WebSocket
通过使用其选择的策略,但在WebSocket协议的边界内使用适当的Pong消息进行回复WebSocket
处理Ping消息。 所述WebSocket
可调用onPing
处理ping消息,在这样做之前或与它平行后。 换句话说,没有保证特定的顺序。 如果在执行处理此Ping消息时发生错误,则将使用此错误调用onError
。 有关处理Ping消息的更多详细信息,请参阅RFC 6455部分5.5.2. Ping和5.5.3. Pong 。该消息将由不超过
125
字节组成:message.remaining() <= 125
。onPing
在onOpen
和(onClose
或onError
)之间调用零次或onError
。如果从此方法抛出异常,或者返回的
CompletionStage
异常完成,则将使用此异常来调用onError
。- 实现要求:
-
此方法的默认实现方式如下:
webSocket.request(1); return null;
- 参数
-
webSocket
- WebSocket -
message
- 消息 - 结果
-
一个完成消息处理的
CompletionStage
; 或null
如果已经完成
-
onPong
default CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message)
收到乒乓消息。乒乓消息可能是未经请求的,或者可能会收到响应先前发送的Ping。 在后一种情况下,乒乓球的内容与原始乒乓球相同。
该消息将由不超过
125
字节组成:message.remaining() <= 125
。onPong
方法在onOpen
和(onClose
或onError
)之间调用零次或onError
。如果从此方法抛出异常或返回的
CompletionStage
异常完成,则将使用此异常来调用onError
。- 实现要求:
-
此方法的默认实现方式如下:
webSocket.request(1); return null;
- 参数
-
webSocket
- WebSocket -
message
- 消息 - 结果
-
一个完成消息处理的
CompletionStage
; 或null
如果已经完成
-
onClose
default CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)
接收到一条关闭消息。关闭消息由状态代码和关闭原因组成。 状态码是
1000 <= code <= 65535
范围内的整数。reason
是一个短字符串,其UTF-8表示不超过123
字节。 有关关闭消息,状态代码和原因的更多详细信息,请参阅RFC 6455第5.5.1. Close和7.4. Status Codes 。返回的
CompletionStage
已经完成(正常或异常)后,WebSocket
通过回复适当的关闭消息完成关闭握手。此实现使用与此消息具有相同代码的空白原因进行回复。
onClose
是在最后调用Listener
。 它最多被调用一次,但在onOpen
之后。 如果从该方法抛出异常,则会被忽略。该
WebSocket
将关闭最早返回的完成CompletionStage
或发送关闭消息。 特别是,如果关闭消息之前已经有sent ,则此调用将完成关闭握手,并且在调用此方法时,WebSocket
将被关闭。- 实现要求:
-
此方法的默认实现方式如下:
return null;
- 参数
-
webSocket
- WebSocket -
statusCode
- 状态码 -
reason
- 的原因 - 结果
-
一个
CompletionStage
完成时可以关闭WebSocket
; 或null
如果可以立即关闭 - 另请参见:
-
WebSocket.NORMAL_CLOSURE
-
onError
default void onError(WebSocket webSocket, Throwable error)
通知发生I / O或协议错误。onError
方法与WebSocket协议中的任何消息不对应。 这是一个合成事件,最后要调用Listener
的方法。 最多只能调用一次,但是在onOpen
之后。 如果从该方法抛出异常,则会被忽略。请注意,WebSocket协议需要在入局目的地发生一些错误,连接必须是致命的。 在这种情况下,实施需要照顾未能通过WebSocket连接的:由时间
onError
被调用时,该WebSocket
将被关闭。 任何未完成的或后续的发送操作都将以IOException
完成。 有关失败WebSocket连接的更多详细信息,请参阅RFC 6455部分7.1.7. Fail the WebSocket Connection 。- API Note:
-
与发送消息相关的错误报告给
CompletableFuture
的sendX
方法返回,而不是这种方法。 - 实现要求:
- 这种方法的默认实现什么都不做。
- 参数
-
webSocket
- WebSocket -
error
- 错误
-
-