```
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消息，则不需要来自侦听器的强制操作。

API Note:

WebSocket和关联的侦听器之间的关系类似于订阅以及类型为Flow的关联订阅服务器之间的关系。

从以下版本开始：

11

嵌套类汇总

嵌套类
变量和类型	接口	描述
`static interface`	`WebSocket.Builder`	WebSocket Clients的建设者。
`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)`	使用给定字符序列中的字符发送文本数据。

- 字段详细信息
  - NORMAL_CLOSURE
```
static final int NORMAL_CLOSURE
```
    WebSocket关闭消息状态代码（ 1000 ），表示正常关闭，这意味着已建立连接的目的。
    
    另请参见：
    
    sendClose(int, String) ， WebSocket.Listener.onClose(WebSocket, int, String) ，常数字段值
- 方法详细信息
  - 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 ，否则将关闭输出。
    
    如果尚未关闭，则输入将保持打开状态，直到调用关闭消息received或abort或发生error 。
    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 of abort will have no effect.

Interface WebSocket

嵌套类汇总

字段汇总

方法摘要

字段详细信息

NORMAL_CLOSURE

方法详细信息

sendText

sendBinary

sendPing

sendPong

sendClose

request

getSubprotocol

isOutputClosed

isInputClosed

abort