软件包  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协议,否则将调用onErrorProtocolException

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

    当该方法返回时,该消息被认为是接收的(特别是如果包含在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和( onCloseonError )之间调用零次或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和( onCloseonError )之间调用零次或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. Ping5.5.3. Pong

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

        onPingonOpen和( onCloseonError )之间调用零次或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和( onCloseonError )之间调用零次或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. Close7.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:
        与发送消息相关的错误报告给 CompletableFuturesendX方法返回,而不是这种方法。
        实现要求:
        这种方法的默认实现什么都不做。
        参数
        webSocket - WebSocket
        error - 错误