模块  java.net.http
软件包  java.net.http

Interface WebSocket.Listener

  • Enclosing interface:
    WebSocket 
    public static interface WebSocket.Listener
    接收界面为WebSocket 。

    WebSocket调用关联侦听器的方法，将其自身作为参数传递。 以线程安全的方式调用这些方法，以便下一个调用可以仅在前一个调用完成之后开始。

    收到数据后， WebSocket调用receive方法。 方法onText ， onBinary ， onPing和onPong必须返回一个CompletionStage一旦消息已被监听收到的完成。 如果侦听器的方法返回null而不是CompletionStage ，则WebSocket行为就像侦听器返回已正常完成的CompletionStage 。

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

    API Note:
    从WebSocket到Listener的严格顺序调用意味着Listener的方法被视为不可重入。 这意味着Listener实现不需要关心可能的递归或它们WebSocket.request于其处理逻辑调用WebSocket.request的顺序。

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

    CompletionStage从接收方法返回■找无关的counter of invocations 。 也就是说，不必完成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; } ... }
    从以下版本开始：
    11

    • 方法详细信息

      • onOpen

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

        这是初始调用，只进行一次。 它通常用于请求更多调用。

        实现要求：
        默认实现相当于： 
           webSocket.request(1);
        参数
        webSocket - 已连接的WebSocket

      • onText

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

        返回CompletionStage将由使用WebSocket作为指示它可能回收CharSequence 。 在CompletionStage完成后，请勿访问CharSequence 。

        实现要求：
        默认实现相当于： 
           webSocket.request(1); return null;
        Implementation Note:
        data始终是合法的UTF-16序列。
        参数
        webSocket - 已接收数据的WebSocket
        data - 数据
        last - 此调用是否完成消息
        结果
        CompletionStage ，当CharSequence可以回收时完成; 或null如果它可以立即回收

      • onBinary

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

        此数据位于从缓冲区位置到其限制的字节中。

        返回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字节。 这些字节位于缓冲区的位置到其限制。

        鉴于在收到ping时WebSocket实现将自动发送一个互惠的pong，很少需要在收到ping时显式发送pong消息。

        返回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 ，它将被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)
        收到一条Close消息，指示WebSocket的输入已关闭。

        这是指定的WebSocket的最后一次调用。 到此调用开始时，WebSocket的输入将被关闭。

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

        如果WebSocket的输出尚未关闭，则此方法返回的CompletionStage将用作指示WebSocket的输出可能已关闭。 WebSocket将在返回的CompletionStage最早完成时关闭其输出，或者调用sendClose或abort方法中的任何一个。

        API Note:
        返回永不完成的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请求任何调用，WebSocket都可以在调用onOpen后随时在关联的侦听器上调用此方法。

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

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