Module java.net.http
Package java.net.http

Interface WebSocket.Listener

封装接口:
WebSocket
public static interface WebSocket.Listener
WebSocket的接收接口。

WebSocket调用相关监听器的方法，并将自身作为参数传递。这些方法以线程安全的方式调用，即下一次调用只能在上一次完成后开始。

当接收到数据时，WebSocket会调用一个接收方法。方法onText、onBinary、onPing和onPong必须返回一个CompletionStage，一旦消息被监听器接收，该CompletionStage就会完成。如果监听器的方法返回的不是CompletionStage而是null，而不是一个已正常完成的CompletionStage，WebSocket将表现为监听器返回了一个已正常完成的CompletionStage。

WebSocket中引发的IOException将导致调用onError并传递该异常（如果输入未关闭）。除非另有说明，如果监听器的方法抛出异常或从方法返回的CompletionStage异常完成，WebSocket将使用此异常调用onError。

API 注意:
WebSocket到Listener的严格顺序调用意味着，特别是Listener的方法被视为非可重入的。这意味着Listener实现不需要担心可能的递归或它们调用WebSocket.request的顺序与其处理逻辑的关系。

如果一个监听器关联多个WebSocket，可能需要仔细注意。在这种情况下，与不同WebSocket实例相关的调用可能不会被排序，甚至可能同时发生。

从接收方法返回的CompletionStage与调用监听器方法的计数器无关。换句话说，CompletionStage不必在接收到监听器方法的更多调用之前完成。以下是一个请求逐个调用的示例监听器，直到累积完整消息，然后处理结果并完成CompletionStage：

    WebSocket.Listener listener = new WebSocket.Listener() {

    List<CharSequence> parts = new ArrayList<>();
    CompletableFuture<?> accumulatedMessage = new CompletableFuture<>();

    public CompletionStage<?> onText(WebSocket webSocket,
                                     CharSequence message,
                                     boolean last) {
        parts.add(message);
        webSocket.request(1);
        if (last) {
            processWholeText(parts);
            parts = new ArrayList<>();
            accumulatedMessage.complete(null);
            CompletionStage<?> cf = accumulatedMessage;
            accumulatedMessage = new CompletableFuture<>();
            return cf;
        }
        return accumulatedMessage;
    }
};
自 JDK 版本:
11

  • Method Details

    • onOpen

      default void onOpen(WebSocket webSocket)
      已连接WebSocket。

      这是初始调用，仅调用一次。通常用于请求更多调用。

      实现要求:
      默认实现等效于: 
      webSocket.request(1);
      参数:
      webSocket - 已连接的WebSocket

    • onText

      default CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last)
      已接收到文本数据。

      返回一个CompletionStage，该CompletionStage将被WebSocket用作指示可以回收CharSequence的信号。在此CompletionStage完成后不要访问CharSequence。

      实现要求:
      默认实现等效于: 
      webSocket.request(1);
return null;
      实现说明:
      data始终是合法的UTF-16序列。
      参数:
      webSocket - 已接收数据的WebSocket
      data - 数据
      last - 此调用是否完成消息
      返回:
      一个CompletionStage，当CharSequence可以被回收时完成；或者如果可以立即回收，则为null

    • onBinary

      default CompletionStage<?> onBinary(WebSocket webSocket, ByteBuffer data, boolean last)
      已接收到二进制数据。

      这些数据位于缓冲区的位置到其限制之间的字节中。

      返回一个CompletionStage，该CompletionStage将被WebSocket用作指示可以回收ByteBuffer的信号。在此CompletionStage完成后不要访问ByteBuffer。

      实现要求:
      默认实现等效于: 
      webSocket.request(1);
return null;
      参数:
      webSocket - 已接收数据的WebSocket
      data - 数据
      last - 此调用是否完成消息
      返回:
      一个CompletionStage，当ByteBuffer可以被回收时完成；或者如果可以立即回收，则为null

    • onPing

      default CompletionStage<?> onPing(WebSocket webSocket, ByteBuffer message)
      已接收到Ping消息。

      根据WebSocket协议的保证，消息由不超过125字节组成。这些字节位于缓冲区的位置到其限制之间。

      由于WebSocket实现在接收到Ping时将自动发送一个对应的Pong，因此在接收到Ping时很少需要显式发送Pong消息。

      返回一个CompletionStage，该CompletionStage将被WebSocket用作信号，可以回收ByteBuffer。在此CompletionStage完成后不要访问ByteBuffer。

      实现要求:
      默认实现等效于: 
      webSocket.request(1);
return null;
      参数:
      webSocket - 已接收消息的WebSocket
      message - 消息
      返回:
      一个CompletionStage，当ByteBuffer可以被回收时完成；或者如果可以立即回收，则为null

    • onPong

      default CompletionStage<?> onPong(WebSocket webSocket, ByteBuffer message)
      已接收到Pong消息。

      根据WebSocket协议的保证，消息由不超过125字节组成。这些字节位于缓冲区的位置到其限制之间。

      返回一个CompletionStage，该CompletionStage将被WebSocket用作信号，可以回收ByteBuffer。在此CompletionStage完成后不要访问ByteBuffer。

      实现要求:
      默认实现等效于: 
      webSocket.request(1);
return null;
      参数:
      webSocket - 已接收消息的WebSocket
      message - 消息
      返回:
      一个CompletionStage，当ByteBuffer可以被回收时完成；或者如果可以立即回收，则为null

    • onClose

      default CompletionStage<?> onClose(WebSocket webSocket, int statusCode, String reason)
      接收到一个关闭消息，指示WebSocket的输入已关闭。

      这是来自指定WebSocket的最后一次调用。在此调用开始时，WebSocket的输入将已关闭。

      关闭消息由状态码和关闭原因组成。状态码是范围为1000 <= code <= 65535的整数。reason是一个UTF-8表示不超过123字节的字符串。

      如果WebSocket的输出尚未关闭，则此方法返回的CompletionStage将被用作WebSocket的输出可以关闭的指示。WebSocket将在返回的CompletionStage完成或调用sendClose或abort方法之一时尽早关闭其输出。

      API 注释:
      返回一个永远不会完成的CompletionStage，有效地禁用了输出的往复闭合。

      要指定自定义关闭代码或原因代码，可以在onClose调用内部调用sendClose方法：

         public CompletionStage<?> onClose(WebSocket webSocket,
                        int statusCode,
                        String reason) {
    webSocket.sendClose(CUSTOM_STATUS_CODE, CUSTOM_REASON);
    return new CompletableFuture<Void>();
}
      实现要求:
      此方法的默认实现返回null，表示应立即关闭输出。
      参数:
      webSocket - 已接收消息的WebSocket
      statusCode - 状态码
      reason - 原因
      返回:
      一个CompletionStage，当WebSocket可以关闭时完成；或null如果可以立即关闭

    • onError

      default void onError(WebSocket webSocket, Throwable error)
      发生了错误。

      这是指定的WebSocket的最后一次调用。在此调用开始时，WebSocket的输入和输出都将被关闭。WebSocket可以在调用了onOpen之后的任何时间在相关侦听器上调用此方法，无论是否已经请求了WebSocket的任何调用。

      如果从此方法抛出异常，则结果行为是未定义的。

      参数:
      webSocket - 发生错误的WebSocket
      error - 错误