Module  jdk.incubator.httpclient
软件包  jdk.incubator.http

Interface WebSocket.Listener

  • Enclosing interface:
    WebSocket 

    public static interface WebSocket.Listener
    一个WebSocket事件和消息的WebSocket 。
    Incubating Feature.将在以后的版本中删除。

    Listener每个方法对应于事件的类型或消息的类型。 该方法的WebSocket参数是WebSocket事件已发生（已收到消息）。 具有相同的WebSocket参数的所有方法都以顺序（和happens-before ）顺序相继调用，可能由不同的线程调用。

    Listener接收到的Listener符合WebSocket协议，否则将调用onError与ProtocolException 。

    如果收到整条消息，则将使用WHOLE标记来调用相应的方法（ onText或onBinary ）。 否则将使用FIRST调用该方法，或多次使用PART ，最后使用LAST标记。 如果上述任何方法引发异常，则onError被调用与相同的WebSocket和此异常。 从onError或onClose抛出的异常被忽略。

    当该方法返回时，该消息被认为是接收的（特别是如果包含在ByteBuffer buffer ，则无论方法返回时是否完成buffer.hasRemaining()的结果，数据被认为完全被接收。

    这些调用开始异步处理，这可能不会以调用结束。 提供协调，方法Listener返回一个CompletionStage 。 CompletionStage表示WebSocket处理消息已经结束。 为方便起见，方法可能会返回null ，按照惯例，这意味着返回一个已经完成的（通常的） CompletionStage 。 如果返回CompletionStage格外完成，然后onError将用相同的调用WebSocket与此异常。

    该消息的控制传递给Listener与该方法的调用。 消息的控制最早返回到WebSocket ，从方法返回null ，或完成从方法返回的CompletionStage 。 WebSocket不能访问该消息，而不在其控制。 Listener不能访问该消息后其控件已被返回到WebSocket 。

    A WebSocket实现从不调用Listener的方法，其中null作为其参数。

    从以下版本开始：
    9

    • 方法详细信息

      • onOpen

        default void onOpen​(WebSocket webSocket)
        通知Listener它连接到提供的WebSocket 。

        onOpen方法与WebSocket协议的任何消息不对应。 这是一个合成事件和第一个被调用的Listener的方法。

        此方法通常用于为邮件创建初始的request 。

        如果一个异常是从此方法抛出，则onError将使用相同的调用WebSocket与此异常。

        实现要求：
        此方法的默认实现方式如下： 
           webSocket.request(1);
        参数
        webSocket - WebSocket

      • onText

        default CompletionStage<?> onText​(WebSocket webSocket,
                                  CharSequence message,
                                  WebSocket.MessagePart part)
        接收短信。

        onText方法在onOpen和（ onClose或onError ）之间调用零次或onError 。

        该消息可以是部分UTF-16序列。 然而，所有消息通过最后的连接将是一个完整的UTF-16序列。

        如果一个异常是从此方法抛出或返回CompletionStage完成分外，然后onError将用相同的调用WebSocket与此异常。

        实现要求：
        此方法的默认实现方式如下： 
           webSocket.request(1); return null;
        Implementation Note:
        此实现只将完整的UTF-16序列传递到 onText方法。
        参数
        webSocket - WebSocket
        message - 消息
        part - 的部分
        结果
        一个完成消息处理的CompletionStage ; 或null如果已经完成

      • onBinary

        default CompletionStage<?> onBinary​(WebSocket webSocket,
                                    ByteBuffer message,
                                    WebSocket.MessagePart part)
        接收二进制消息。

        onBinary方法在onOpen和（ onClose或onError ）之间调用零次或onError 。

        如果一个异常是从此方法抛出或返回CompletionStage完成分外，然后onError将用相同的调用WebSocket与此异常。

        实现要求：
        此方法的默认实现方式如下： 
           webSocket.request(1); return null;
        参数
        webSocket - WebSocket
        message - 消息
        part - 的部分
        结果
        一个完成消息处理的CompletionStage ; 或null如果已经完成

      • onPing

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

        Ping消息可以由客户端或服务器发送或接收。 它可以用作keepalive或作为验证远程端点仍然响应的手段。

        WebSocket通过使用其选择的策略，但在WebSocket协议的边界内使用适当的Pong消息进行回复WebSocket处理Ping消息。 所述WebSocket可调用onPing处理ping消息，在这样做之前或与它平行后。 换句话说，没有保证特定的顺序。 如果在执行处理此Ping消息时发生错误，则将使用此错误调用onError 。 有关处理Ping消息的更多详细信息，请参阅RFC 6455部分5.5.2. Ping和5.5.3. Pong 。

        该消息将由不超过125字节组成： message.remaining() <= 125 。

        onPing在onOpen和（ onClose或onError ）之间调用零次或onError 。

        如果从此方法抛出异常，或者返回的CompletionStage异常完成，则将使用此异常来调用onError 。

        实现要求：
        此方法的默认实现方式如下： 
           webSocket.request(1); return null;
        参数
        webSocket - WebSocket
        message - 消息
        结果
        一个完成消息处理的CompletionStage ; 或null如果已经完成

      • onPong

        default CompletionStage<?> onPong​(WebSocket webSocket,
                                  ByteBuffer message)
        收到乒乓消息。

        乒乓消息可能是未经请求的，或者可能会收到响应先前发送的Ping。 在后一种情况下，乒乓球的内容与原始乒乓球相同。

        该消息将由不超过125字节组成： message.remaining() <= 125 。

        onPong方法在onOpen和（ onClose或onError ）之间调用零次或onError 。

        如果从此方法抛出异常或返回的CompletionStage异常完成，则将使用此异常来调用onError 。

        实现要求：
        此方法的默认实现方式如下： 
           webSocket.request(1); return null;
        参数
        webSocket - WebSocket
        message - 消息
        结果
        一个完成消息处理的CompletionStage ; 或null如果已经完成

      • onClose

        default CompletionStage<?> onClose​(WebSocket webSocket,
                                   int statusCode,
                                   String reason)
        接收到一条关闭消息。

        关闭消息由状态代码和关闭原因组成。 状态码是1000 <= code <= 65535范围内的整数。 reason是一个短字符串，其UTF-8表示不超过123字节。 有关关闭消息，状态代码和原因的更多详细信息，请参阅RFC 6455第5.5.1. Close和7.4. Status Codes 。

        返回的CompletionStage已经完成（正常或异常）后， WebSocket通过回复适当的关闭消息完成关闭握手。

        此实现使用与此消息具有相同代码的空白原因进行回复。

        onClose是在最后调用Listener 。 它最多被调用一次，但在onOpen之后。 如果从该方法抛出异常，则会被忽略。

        该WebSocket将关闭最早返回的完成CompletionStage或发送关闭消息。 特别是，如果关闭消息之前已经有sent ，则此调用将完成关闭握手，并且在调用此方法时， WebSocket将被关闭。

        实现要求：
        此方法的默认实现方式如下： 
           return null;
        参数
        webSocket - WebSocket
        statusCode - 状态码
        reason - 的原因
        结果
        一个CompletionStage完成时可以关闭WebSocket ; 或null如果可以立即关闭
        另请参见：
        WebSocket.NORMAL_CLOSURE

      • onError

        default void onError​(WebSocket webSocket,
                     Throwable error)
        通知发生I / O或协议错误。

        onError方法与WebSocket协议中的任何消息不对应。 这是一个合成事件，最后要调用Listener的方法。 最多只能调用一次，但是在onOpen之后。 如果从该方法抛出异常，则会被忽略。

        请注意，WebSocket协议需要在入局目的地发生一些错误，连接必须是致命的。 在这种情况下，实施需要照顾未能通过WebSocket连接的：由时间onError被调用时，该WebSocket将被关闭。 任何未完成的或后续的发送操作都将以IOException完成。 有关失败WebSocket连接的更多详细信息，请参阅RFC 6455部分7.1.7. Fail the WebSocket Connection 。

        API Note:
        与发送消息相关的错误报告给 CompletableFuture的 sendX方法返回，而不是这种方法。
        实现要求：
        这种方法的默认实现什么都不做。
        参数
        webSocket - WebSocket
        error - 错误