-
public interface WebSocket
符合RFC 6455的WebSocket客户端。
Incubating Feature.将在以后的版本中删除。A
WebSocket
通过TCP连接提供全双工通信。要创建一个
WebSocket
使用builder 。 一旦构建了一个WebSocket
,就可以发送和接收消息了。 当不再需要WebSocket
,必须关闭:关闭消息必须是sent和received 。WebSocket
也可能关闭abruptly 。一旦关闭,
WebSocket
仍然是closed ,无法重新打开。通过
WebSocket.send{X}
和WebSocket.Listener
.on{X}
方法异步发送和接收类型为X
(其中X
为文本,二进制,乒乓,乒乓或关闭)的WebSocket.send{X}
。 每个方法返回一个CompletionStage
,当操作完成时,它将完成。请注意,只有requested才会收到(任何类型的)消息。
允许一个未完成的发送操作。 在上一个完成之前不能发起进一步的发送操作。 发送时,在返回的
CompletableFuture
完成(正常或异常)之前,不能修改消息。文本和二进制消息可以作为一个整体或部分发送和接收。 整个消息作为一个或多个相应方法的调用的顺序传送,其中最后一个调用通过附加的方法参数被识别。
如果消息包含在一个
ByteBuffer
中 ,则会考虑从buffer
的buffer的buffer
的limit
buffer
的字节 。除非另有说明,
null
参数值将导致方法和构造函数抛出NullPointerException
。- Implementation Note:
-
此实现的方法在返回
CompletableFuture
之前不会阻塞。 - 从以下版本开始:
- 9
-
-
Nested Class Summary
Nested Classes Modifier and Type 接口 描述 static interface
WebSocket.Builder
用于创建WebSocket
实例的构建器。static interface
WebSocket.Listener
一个WebSocket
事件和消息的WebSocket
。static class
WebSocket.MessagePart
在可能接收到部分消息的情况下,由WebSocket.Listener
使用的标记。
-
Field Summary
Fields Modifier and Type Field 描述 static int
NORMAL_CLOSURE
WebSocket关闭消息状态码(1000
),表示正常关闭,意味着建立连接的目的已经实现。
-
方法摘要
所有方法 接口方法 抽象方法 Modifier and Type 方法 描述 void
abort()
突然关闭了WebSocket
。String
getSubprotocol()
返回一个 subprotocol ,已被选为该WebSocket
。boolean
isClosed()
告诉WebSocket
是否关闭。void
request(long n)
允许n
由接收多个消息Listener
。CompletableFuture<WebSocket>
sendBinary(ByteBuffer message, boolean isLast)
从给定的ByteBuffer
发送带有字节的二进制消息。CompletableFuture<WebSocket>
sendClose(int statusCode, String reason)
发送关闭消息与给定的状态代码和原因。CompletableFuture<WebSocket>
sendPing(ByteBuffer message)
从给定的ByteBuffer发送带有字节的Ping消息。CompletableFuture<WebSocket>
sendPong(ByteBuffer message)
从给定的ByteBuffer发送带有字节的Pong消息。CompletableFuture<WebSocket>
sendText(CharSequence message, boolean isLast)
发送带有CharSequence
字符的CharSequence
。
-
-
-
方法详细信息
-
sendText
CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast)
发送带有CharSequence
字符的CharSequence
。返回一个
CompletableFuture<WebSocket>
,当消息已发送或完成异常(如果发生错误)时,它将正常完成。CharSequence
不能修改,直到返回的CompletableFuture
完成(正常或异常)。返回的
CompletableFuture
可以完美地完成:-
IllegalArgumentException
- 如果message
是格式错误的UTF-16序列 -
IllegalStateException
- 如果WebSocket
关闭; 或者如果已发送关闭消息; 或者如果有未完成的发送操作; 或者如果先前的二进制消息与isLast == false
一起isLast == false
-
IOException
- 如果在此操作期间发生I / O错误; 或如果WebSocket
由于错误而关闭;
- Implementation Note:
-
此实现不接受部分UTF-16序列。
如果这样一个序列被传递,返回的
CompletableFuture
完成了IOException
。 - 参数
-
message
- 消息 -
isLast
-true
如果这是消息的最后一部分,false
否则 - 结果
-
一个
CompletableFuture
与这个WebSocket
-
-
sendBinary
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast)
发送二进制消息与给定的ByteBuffer
字节。返回一个
CompletableFuture<WebSocket>
,当消息已发送或完成异常(如果发生错误)时,它将正常完成。返回的
CompletableFuture
可以完成以下功能:-
IllegalStateException
- 如果WebSocket
关闭了; 或者如果已发送关闭消息; 或者如果有未完成的发送操作; 或者如果以前发送的短信是isLast == false
-
IOException
- 如果在此操作期间发生I / O错误; 或者如果WebSocket
由于错误而关闭
- 参数
-
message
- 消息 -
isLast
-true
如果这是消息的最后一部分,false
否则 - 结果
-
一个
CompletableFuture
这个WebSocket
-
-
sendPing
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
从给定的ByteBuffer发送带有字节的Ping消息。返回一个
CompletableFuture<WebSocket>
,当消息已经发送或完成异常时,如果发生错误,它将正常完成。Ping消息可以由客户端或服务器发送或接收。 它可以用作keepalive或作为验证远程端点仍然响应的手段。
该消息必须由不超过
125
字节组成:message.remaining() <= 125
。返回的
CompletableFuture
可以完美地完成:-
IllegalArgumentException
- 如果是message.remaining() > 125
-
IllegalStateException
- 如果WebSocket
是关闭的; 或者如果已发送关闭消息; 或者如果有未完成的发送操作 -
IOException
- 如果在此操作期间发生I / O错误; 或者如果WebSocket
因错误而关闭
- 参数
-
message
- 消息 - 结果
-
一个
CompletableFuture
与这个WebSocket
-
-
sendPong
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
从给定的ByteBuffer发送带有字节的Pong消息。返回一个
CompletableFuture<WebSocket>
,当消息已发送或完成异常(如果发生错误)时,它将正常完成。乒乓消息可能是未经请求的,也可能是响应先前收到的Ping发送的。 在后一种情况下,乒乓球的内容必须与原始的平面相同。
该消息必须包含不超过
125
字节:message.remaining() <= 125
。返回的
CompletableFuture
可以完成以下功能:-
IllegalArgumentException
- 如果是message.remaining() > 125
-
IllegalStateException
- 如果WebSocket
关闭; 或者如果已发送关闭消息; 或者如果有未完成的发送操作 -
IOException
- 如果在此操作中发生I / O错误; 或者如果WebSocket
因错误而关闭
- 参数
-
message
- 消息 - 结果
-
一个
CompletableFuture
这个WebSocket
-
-
sendClose
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
发送关闭消息与给定的状态代码和原因。当调用此方法时,不会再发送进一步的消息。
statusCode
是一个整数,范围1000 <= code <= 4999
。 然而,在一些实现中并不是所有状态代码都是合法的。 无论实现的,1000
始终是法律和1002
,1003
,1005
,1006
,1007
,1009
,1010
,1012
,1013
和1015
始终是非法的代码。reason
是一个短字符串,必须具有不超过123
字节的UTF-8表示形式。 有关关闭消息,状态代码和原因的更多详细信息,请参阅RFC 6455第5.5.1. Close和7.4. Status Codes 。该方法返回一个
CompletableFuture<WebSocket>
,当消息已经被发送或异常发生时异常地完成。返回的
CompletableFuture
可以完美地完成:-
IllegalArgumentException
- 如果statusCode
具有非法值; 或者如果reason
没有长度为<= 123
的UTF-8表示 -
IOException
- 如果在此操作期间发生I / O错误; 或WebSocket
由于错误而关闭
如果此方法已被调用或
WebSocket
关闭,则此方法的后续调用不起作用,返回的CompletableFuture
正常完成。如果关闭消息已经在received之前,则此调用将完成关闭握手,并且在返回的
CompletableFuture
完成时,WebSocket
将关闭。- 参数
-
statusCode
- 状态码 -
reason
- 的原因 - 结果
-
一个
CompletableFuture
这个WebSocket
-
-
request
void request(long n)
允许n
由接收多个消息Listener
。如果收到关闭消息,
WebSocket
关闭或发生错误,接收到的消息的实际数量可能会更少。一个刚刚构建的
WebSocket
,还没有要求任何东西。 通常,消息的初始请求是在Listener.onOpen
中进行的 。如果
WebSocket
被关闭,则调用此方法没有任何作用。- Implementation Note:
-
该实现不区分部分消息和整个消息,因为事先不知道如何接收消息。
如果服务器发送的消息多于请求,则该实现将这些消息排队在TCP连接上,最终可能会强制发送方停止通过TCP流控制发送。
- 参数
-
n
- 消息的数量 - 异常
-
IllegalArgumentException
- 如果是n < 0
-
getSubprotocol
String getSubprotocol()
返回一个 subprotocol ,已被选为该WebSocket
。- 结果
-
一个子协议,或一个空的
String
如果没有
-
isClosed
boolean isClosed()
告诉WebSocket
是否关闭。当关闭
WebSocket
,不再发送或接收到其他消息。- 结果
-
true
如果WebSocket
关闭,否则为false
-
abort
void abort() throws IOException
突然关闭WebSocket
。可以随时调用此方法。 此方法关闭底层TCP连接,并将
WebSocket
置于关闭状态。其结果是
Listener.onClose
将被调用,除非任何onClose
或者onError
之前已经调用。 在这种情况下,不会发生额外的调用。如果
WebSocket
已经关闭,则调用此方法没有任何作用。- 异常
-
IOException
- 如果发生I / O错误
-
-