-
public interface WebSocket
WebSocket客户端。通过
WebSocket.Builder
创建WebSocket
实例。WebSocket有输入和输出端。 这些方面彼此独立。 一侧可以打开或关闭。 关闭后,侧面保持关闭状态。 WebSocket消息通过
WebSocket
发送,并通过WebSocket.Listener
关联的WebSocket
接收。 可以发送消息直到WebSocket的输出关闭,并在WebSocket的输入关闭之前一直接收。的发送方法是任何的
sendText
,sendBinary
,sendPing
,sendPong
和sendClose
的方法WebSocket
。 send方法启动发送操作并返回CompletableFuture
,该操作在操作完成后完成。 如果CompletableFuture
正常完成,则认为操作成功。 如果CompletableFuture
异常完成,则认为操作失败。 已启动但尚未完成的操作被视为待处理。甲接收方法是任何的
onText
,onBinary
,onPing
,onPong
和onClose
的方法Listener
。 WebSocket通过在侦听器上调用receive方法来启动接收操作。 然后,侦听器必须返回CompletionStage
,该操作在操作完成后完成。为了控制消息的接收,WebSocket维护一个internal counter 。 此计数器的值是WebSocket尚未调用receive方法的次数。 虽然此计数器为零,但WebSocket不会调用接收方法。 该计数器加
n
时request(n)
被调用。 当WebSocket调用receive方法时,计数器减1。onOpen
和onError
不接收方法。 WebSocket在侦听器上的任何其他方法之前调用onOpen
。 WebSocket最多调用一次onOpen
。 WebSocket可以在任何给定时间调用onError
。 如果WebSocket调用onError
或onClose
,则无论计数器的值如何,都不会调用其他侦听器的方法。 对于新构建的WebSocket,计数器为零。除非另有说明,
null
论证会造成的方法WebSocket
扔NullPointerException
,同样,WebSocket
不会通过null
参数的方法Listener
。 一个网页套接字的状态不会被抛出或返回的调用改变CompletableFuture
,随着一个完成NullPointerException
,IllegalArgumentException
,IllegalStateException
例外。WebSocket
通过回复Pong和Close消息自动处理收到的Ping和Close消息(根据WebSocket协议)。 如果侦听器收到Ping或Close消息,则不需要来自侦听器的强制操作。
-
-
嵌套类汇总
嵌套类 变量和类型 接口 描述 static interface
WebSocket.Builder
static interface
WebSocket.Listener
接收界面为WebSocket
。
-
字段汇总
字段 变量和类型 字段 描述 static int
NORMAL_CLOSURE
WebSocket关闭消息状态代码(1000
),表示正常关闭,这意味着已建立连接的目的。
-
方法摘要
所有方法 实例方法 抽象方法 变量和类型 方法 描述 void
abort()
突然关闭此WebSocket的输入和输出。String
getSubprotocol()
返回此WebSocket使用的子协议。boolean
isInputClosed()
判断此WebSocket的输入是否已关闭。boolean
isOutputClosed()
判断此WebSocket的输出是否已关闭。void
request(long n)
增加接收方法调用的计数器。CompletableFuture<WebSocket>
sendBinary(ByteBuffer data, boolean last)
使用给定缓冲区中的字节发送二进制数据。CompletableFuture<WebSocket>
sendClose(int statusCode, String reason)
通过发送具有给定状态代码和原因的Close消息来启动此WebSocket输出的有序关闭。CompletableFuture<WebSocket>
sendPing(ByteBuffer message)
从给定缓冲区发送包含字节的Ping消息。CompletableFuture<WebSocket>
sendPong(ByteBuffer message)
从给定缓冲区发送包含字节的Pong消息。CompletableFuture<WebSocket>
sendText(CharSequence data, boolean last)
使用给定字符序列中的字符发送文本数据。
-
-
-
方法详细信息
-
sendText
CompletableFuture<WebSocket> sendText(CharSequence data, boolean last)
使用给定字符序列中的字符发送文本数据。在从此方法返回的
CompletableFuture
完成之前,不得修改字符序列。从此方法返回的
CompletableFuture
可以异常完成:-
IllegalStateException
- 如果存在挂起的文本或二进制发送操作,或者如果先前的二进制数据未完成该消息 -
IOException
- 如果发生I / O错误,或者输出已关闭
- Implementation Note:
- 如果
data
是格式错误的UTF-16序列,则操作将失败并显示IOException
。 - 参数
-
data
- 数据 -
last
-true
如果此调用完成消息,否则为false
- 结果
- 使用此WebSocket完成数据发送后的
CompletableFuture
-
-
sendBinary
CompletableFuture<WebSocket> sendBinary(ByteBuffer data, boolean last)
使用给定缓冲区中的字节发送二进制数据。数据位于从缓冲区位置到其限制的字节中。 正常完成从此方法返回的
CompletableFuture
后,缓冲区将没有剩余的字节。 之后才能访问缓冲区。从此方法返回的
CompletableFuture
可以异常完成:-
IllegalStateException
- 如果存在挂起的文本或二进制发送操作,或者先前的文本数据未完成消息 -
IOException
- 如果发生I / O错误,或者输出已关闭
- 参数
-
data
- 数据 -
last
-true
如果此调用完成消息,否则为false
- 结果
-
CompletableFuture
,使用此WebSocket完成数据发送时
-
-
sendPing
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
从给定缓冲区发送包含字节的Ping消息。该消息包含从缓冲区位置到其限制的不超过
125
个字节。 正常完成从此方法返回的CompletableFuture
后,缓冲区将没有剩余的字节。 之后才能访问缓冲区。从此方法返回的
CompletableFuture
可以异常完成:-
IllegalStateException
- 如果有挂起的ping或pong发送操作 -
IllegalArgumentException
- 如果消息太长 -
IOException
- 如果发生I / O错误,或者输出已关闭
- 参数
-
message
- 消息 - 结果
- 使用此WebSocket完成Ping消息的
CompletableFuture
-
-
sendPong
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
从给定缓冲区发送包含字节的Pong消息。该消息包含从缓冲区位置到其限制的不超过
125
个字节。 正常完成从此方法返回的CompletableFuture
后,缓冲区将没有剩余的字节。 之后才能访问缓冲区。鉴于在收到ping时WebSocket实现将自动发送一个互惠的pong,很少需要显式发送pong消息。
从此方法返回的
CompletableFuture
可以异常完成:-
IllegalStateException
- 如果有挂起的ping或pong发送操作 -
IllegalArgumentException
- 如果消息太长 -
IOException
- 如果发生I / O错误,或者输出已关闭
- 参数
-
message
- 消息 - 结果
- 使用此WebSocket完成Pong消息的
CompletableFuture
-
-
sendClose
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
通过发送具有给定状态代码和原因的Close消息来启动此WebSocket输出的有序关闭。所述
statusCode
是从范围内的整数1000 <= code <= 4999
。 状态代码1002
,1003
,1006
,1007
,1009
,1010
,1012
,1013
和1015
是非法的。 与其他状态代码相关的行为是特定于实现的。 合法的reason
是一个字符串,其UTF-8表示不超过123
字节。从此方法返回的
CompletableFuture
可以异常完成:-
IllegalArgumentException
- 如果statusCode
是非法的,或者reason
是非法的 -
IOException
- 如果发生I / O错误,或者输出已关闭
除非从此方法返回的
CompletableFuture
以IllegalArgumentException
完成,或者方法抛出NullPointerException
,否则将关闭输出。- API Note:
- 在典型情况下,使用提供的整数常量
NORMAL_CLOSURE
作为状态代码和空字符串作为原因:CompletableFuture<WebSocket> webSocket = ... webSocket.thenCompose(ws -> ws.sendText("Hello, ", false)) .thenCompose(ws -> ws.sendText("world!", true)) .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, "")) .join();
sendClose
方法不会关闭此WebSocket的输入。 它只是通过发送Close消息来关闭此WebSocket的输出。 要强制关闭输入,请调用abort
方法。 以下是发送Close消息,然后启动计时器的应用程序示例。 一旦在指定的超时内没有收到任何数据,定时器就会熄灭并且警报中止WebSocket
:MyAlarm alarm = new MyAlarm(webSocket::abort); WebSocket.Listener listener = new WebSocket.Listener() { public CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) { alarm.snooze(); ... } ... }; ... Runnable startTimer = () -> { MyTimer idleTimer = new MyTimer(); idleTimer.add(alarm, 30, TimeUnit.SECONDS); }; webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer);
- 参数
-
statusCode
- 状态码 -
reason
- 原因 - 结果
- 使用此WebSocket完成关闭消息的
CompletableFuture
-
-
request
void request(long n)
增加接收方法调用的计数器。这会的WebSocket调用
onText
,onBinary
,onPing
,onPong
或onClose
对相关监听器方法(即接收方法)到n
多次。- API Note:
- 此方法的参数是从此WebSocket请求到关联侦听器的调用次数,而不是消息数。 有时,可以在单个调用中将消息传递给侦听器,但并非总是如此。 例如,Ping,Pong和Close消息分别在
onPong
和onClose
方法的单个调用中onPing
。 但是,文本和二进制消息是否在onText
和onBinary
方法的单个调用中onText
取决于这些方法的布尔参数(last
)。 如果last
是false
,则消息的数量超过已传递给调用的消息。下面是一个侦听器的示例,一次一个地请求调用,直到累积完整的消息,然后处理结果:
WebSocket.Listener listener = new WebSocket.Listener() { StringBuilder text = new StringBuilder(); public CompletionStage<?> onText(WebSocket webSocket, CharSequence message, boolean last) { text.append(message); if (last) { processCompleteTextMessage(text); text = new StringBuilder(); } webSocket.request(1); return null; } ... }
- 参数
-
n
- 调用次数 - 异常
-
IllegalArgumentException
- 如果是n <= 0
-
getSubprotocol
String getSubprotocol()
返回此WebSocket使用的子协议。- 结果
- 子协议,如果没有子协议,则为空字符串
-
isOutputClosed
boolean isOutputClosed()
判断此WebSocket的输出是否已关闭。如果此方法返回
true
,则后续调用也将返回true
。- 结果
-
true
如果关闭,false
否则
-
isInputClosed
boolean isInputClosed()
判断此WebSocket的输入是否已关闭。如果此方法返回
true
,则后续调用也将返回true
。- 结果
-
true
如果关闭,false
否则
-
abort
void abort()
Closes this WebSocket's input and output abruptly.When this method returns both the input and the output will have been closed. Any pending send operations will fail with
IOException
. Subsequent invocations ofabort
will have no effect.
-
-