模块 java.net.http
包 java.net.http

接口 WebSocket

public interface WebSocket
WebSocket 客户端。

WebSocket 个实例是通过 WebSocket.Builder 创建的。

WebSocket 有一个输入端和一个输出端。这些方面彼此独立。一侧可以打开或关闭。一旦关闭，侧面将保持关闭状态。 WebSocket 消息通过 WebSocket 发送，并通过与其关联的 WebSocket.Listener 接收。在 WebSocket 的输出关闭之前可以发送消息，在 WebSocket 的输入关闭之前可以接收消息。

发送方法是 WebSocket 的 sendText 、 sendBinary 、 sendPing 、 sendPong 和 sendClose 方法中的任何一个。 send 方法启动发送操作并返回一个 CompletableFuture ，一旦操作完成就完成。如果 CompletableFuture 正常完成，则认为操作成功。如果 CompletableFuture 异常完成，则操作被视为失败。已启动但尚未完成的操作被视为未决。

接收方法是 Listener 的 onText 、 onBinary 、 onPing 、 onPong 和 onClose 方法中的任何一个。 WebSocket 通过调用监听器上的接收方法来启动接收操作。然后，监听器必须返回一个 CompletionStage，一旦操作完成，它就会完成。

为了控制消息的接收，WebSocket 维护一个 内部计数器 。此计数器的值是 WebSocket 尚未调用接收方法的次数。当此计数器为零时，WebSocket 不会调用接收方法。当调用 request(n) 时，计数器递增 n。当 WebSocket 调用接收方法时，计数器减一。 onOpen 和 onError 不是接收方法。 WebSocket 在监听器上调用 onOpen 之前调用任何其他方法。 WebSocket 最多调用 onOpen 一次。 WebSocket 可以在任何给定时间调用 onError。如果 WebSocket 调用 onError 或 onClose ，则无论计数器的值如何，都不会调用进一步的监听器方法。对于新建的 WebSocket，计数器为零。

除非另有说明，否则 null 参数将导致 WebSocket 的方法抛出 NullPointerException ，类似地，WebSocket 不会将 null 参数传递给 Listener 的方法。 WebSocket 的状态不会被抛出或返回 CompletableFuture 的调用更改，该 CompletableFuture 以 NullPointerException 、 IllegalArgumentException 、 IllegalStateException 异常之一完成。

WebSocket 通过回复 Pong 和 Close 消息自动处理接收到的 Ping 和 Close 消息（根据 WebSocket 协议）。如果监听器收到 Ping 或 Close 消息，则不需要监听器强制执行任何操作。

API 注意：
WebSocket 和关联的监听器之间的关系类似于订阅和类型为 Flow 的关联订阅者之间的关系。
自从：
11

  • 字段详细信息

  • 方法详情

    • sendText

      CompletableFuture <WebSocket > sendText(CharSequence  data, boolean last)
      发送包含给定字符序列中的字符的文本数据。

      在此方法返回的 CompletableFuture 完成之前，不得修改字符序列。

      从此方法返回的 CompletableFuture 可以异常完成：

      • IllegalStateException - 如果有待处理的文本或二进制发送操作，或者如果先前的二进制数据未完成消息
      • IOException - 如果发生 I/O 错误，或者输出关闭
      实现注意事项：
      如果 data 是格式错误的 UTF-16 序列，则操作将失败并返回 IOException。
      参数：
      data - 数据
      last - true 如果此调用完成消息，false 否则
      返回：
      一个 CompletableFuture 在数据发送后使用此 WebSocket 完成

    • 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 可以异常完成：

      参数：
      message - 消息
      返回：
      一个 CompletableFuture 在发送 Ping 消息时使用此 WebSocket 完成

    • sendPong

      CompletableFuture <WebSocket > sendPong(ByteBuffer  message)
      从给定缓冲区发送带有字节的 Pong 消息。

      该消息包含从缓冲区位置到其限制的不超过 125 个字节。从该方法返回的 CompletableFuture 正常完成后，缓冲区将没有剩余字节。在此之前不得访问缓冲区。

      鉴于 WebSocket 实现将在收到 ping 时自动发送相互 pong，因此很少需要显式发送 pong 消息。

      从此方法返回的 CompletableFuture 可以异常完成：

      参数：
      message - 消息
      返回：
      一个 CompletableFuture 完成，使用这个 WebSocket，当 Pong 消息被发送时

    • 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 可以异常完成：

      除非从此方法返回的 CompletableFuture 以 IllegalArgumentException 完成，或者该方法抛出 NullPointerException ，否则输出将被关闭。

      如果尚未关闭，输入将保持打开状态，直到关闭消息 已收到 或 abort 被调用，或者 error 发生。

      API 注意：
      在典型情况下，使用提供的整数常量 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 - 原因
      返回：
      一个 CompletableFuture 在发送关闭消息时使用此 WebSocket 完成

    • request

      void request(long n)
      增加接收方法调用的计数器。

      此 WebSocket 将在关联的监听器（即接收方法）上调用 onText、onBinary、onPing、onPong 或 onClose 方法，最多 n 次。

      API 注意：
      此方法的参数是从此 WebSocket 向关联监听器请求的调用次数，而不是消息数。有时，一条消息可能会在一次调用中传递给监听器，但并非总是如此。例如，Ping、Pong 和 Close 消息分别在 onPing、onPong 和 onClose 方法的单次调用中传送。但是，是否在 onText 和 onBinary 方法的单次调用中传递文本和二进制消息取决于这些方法的布尔参数 (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()
      突然关闭此 WebSocket 的输入和输出。

      当此方法返回时，输入和输出都已关闭。任何挂起的发送操作都将失败并返回 IOException。 abort 的后续调用将无效。