モジュール jdk.incubator.httpclient
パッケージ jdk.incubator.http

インタフェースWebSocket.Listener

  • 含まれているインタフェース:
    WebSocket

    public static interface WebSocket.Listener
    WebSocketのイベントとメッセージのリスナーです。
    インキュベーション機能。将来のリリースで削除されます。

    Listenerの各メソッドは、イベントの型またはメッセージの型に対応します。 メソッドのWebSocket引数は、イベントが発生したWebSocketです。(メッセージが受信された)がオンです。 同じWebSocket引き数を持つすべてのメソッドは、異なるスレッドによって、順番に(とhappens-before)の順番で呼び出されます。

    • onOpen
      このメソッドが最初に呼び出されます。
    • onText、onBinary、onPing、onPong
      これらのメソッドは、onOpenの後に0回以上呼び出されます。
    • onClose, onError
      これらのメソッドの1つだけが呼び出され、そのメソッドが最後に呼び出されます。

    Listenerによって受信されたメッセージは、WebSocketプロトコルに準拠します。そうでなければ、onErrorがProtocolExceptionで呼び出されます。

    メッセージ全体が受信されると、対応するメソッド(onTextまたはonBinary)がWHOLEマーカーとともに呼び出されます。 そうでなければ、メソッドはFIRST、PARTで0回以上、そして最後にLASTマーカーで呼び出されます。 上記のいずれかのメソッドが例外をスローすると、同じWebSocketとこの例外を使用してonErrorが呼び出されます。 onErrorまたはonCloseからスローされた例外は無視されます。

    メソッドが返ってくると、メッセージは受信されたとみなされます(特に、ByteBuffer bufferに含まれていると、メソッドの戻り時に結果 buffer.hasRemaining()に関係なくデータは完全に受信されたものとみなされます)。 その後、さらなるメッセージを受信することができます。

    これらの呼び出しは、非同期処理を開始します。 調整を提供するために、ListenerのメソッドはCompletionStageを返します。 CompletionStageは、メッセージの処理が終了したことをWebSocketに通知します。 便宜上、メソッドはnullを返します。(慣例により)既に完了した(通常) CompletionStageを返すことと同じ意味です。 返されたCompletionStageが例外的に完了すると、同じWebSocketとこの例外でonErrorが呼び出されます。

    メッセージの制御は、メソッドの呼び出しとともにListenerに渡されます。 メソッドのnullを返すか、メソッドから返されたCompletionStageの完了を返すかのどちらか早い段階で、メッセージの制御が WebSocketに戻ります。 WebSocketは、制御に含まれていない間はメッセージにアクセスしません。 Listenerは、その制御がWebSocketに戻された後でメッセージにアクセスしてはなりません。

    WebSocketの実装では、nullを引数としてListenerメソッドを呼び出すことはありません。

    導入されたバージョン:
    9

    • メソッドの詳細

      • onOpen

        default void onOpen​(WebSocket webSocket)
        提供されたWebSocketに接続されていることをListenerに通知します。

        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)の間で0回以上呼び出されます。

        このメッセージは、部分的なUTF-16シーケンスです。 ただし、最後までのすべてのメッセージの連結は、UTF-16全体のシーケンスになります。

        このメソッドから例外がスローされた場合、または返された CompletionStageが例外的に完了した場合、onErrorは同じWebSocketとこの例外で呼び出されます。

        実装要件:
        このメソッドのデフォルトの実装は、次のように動作します: 
        
     webSocket.request(1);
     return null;
        実装上の注意:
        この実装は、完全なUTF-16シーケンスのみをonTextメソッドに渡します。
        パラメータ:
        webSocket - WebSocket
        message - メッセージ
        part - 一部
        戻り値:
        メッセージ処理が完了したときに完了するCompletionStage。すでに完了している場合はnull

      • onBinary

        default CompletionStage<?> onBinary​(WebSocket webSocket,
                                    ByteBuffer message,
                                    WebSocket.MessagePart part)
        バイナリ・メッセージを受信します。

        onBinaryメソッドは、onOpenと(onCloseまたはonError)の間で0回以上呼び出されます。

        このメソッドから例外がスローされた場合、または返された CompletionStageが例外的に完了した場合、onErrorは同じWebSocketとこの例外で呼び出されます。

        実装要件:
        このメソッドのデフォルトの実装は、次のように動作します: 
        
     webSocket.request(1);
     return null;
        パラメータ:
        webSocket - WebSocket
        message - メッセージ
        part - 一部
        戻り値:
        メッセージ処理が完了したときに完了するCompletionStage。すでに完了している場合はnull

      • onPing

        default CompletionStage<?> onPing​(WebSocket webSocket,
                                  ByteBuffer message)
        PINGメッセージを受信します。

        Pingメッセージは、クライアントまたはサーバーのいずれかによって送受信されます。 キープアライブとして、またはリモート・エンドポイントがまだ応答していることを確認する手段として機能します。

        WebSocketは、WebSocketプロトコルの境界内で、選択した戦略を使用して適切なPongメッセージで応答することによって、Pingメッセージを処理します。 WebSocketは、Pingメッセージを処理する前に、その前に、またはそれと並行して、onPingを呼び出します。 言い換えれば、特にオーダーは保証されていません。 インプリメンテーションがこのPingメッセージを処理しているときにエラーが発生すると、onErrorがこのエラーとともに呼び出されます。 Pingメッセージの処理の詳細については、RFC 6455のセクション5.5.2。Pingと「5.5.3。ポン」を参照してください。

        メッセージは、125バイト以下で構成されます: message.remaining() <= 125。

        onPingは、onOpenと(onCloseまたはonError)の間で0回以上呼び出されます。

        このメソッドから例外がスローされた場合、または返された CompletionStageが例外的に完了した場合、onErrorがこの例外とともに呼び出されます。

        実装要件:
        このメソッドのデフォルトの実装は、次のように動作します: 
        
     webSocket.request(1);
     return null;
        パラメータ:
        webSocket - WebSocket
        message - メッセージ
        戻り値:
        メッセージ処理が完了したときに完了するCompletionStage。すでに完了している場合はnull

      • onPong

        default CompletionStage<?> onPong​(WebSocket webSocket,
                                  ByteBuffer message)
        Pongメッセージを受信します。

        Pongメッセージは、未請求であってもよいし、以前に送信されたPingにレスポンスして受信されてもよい。 後者の場合、Pongの内容は元のPingと同じです。

        メッセージは、125バイト以下で構成されます: message.remaining() <= 125。

        onPongメソッドは、onOpenと(onCloseまたはonError)の間で0回以上呼び出されます。

        このメソッドから例外がスローされた場合、または返された CompletionStageが例外的に完了した場合、onErrorがこの例外とともに呼び出されます。

        実装要件:
        このメソッドのデフォルトの実装は、次のように動作します: 
        
     webSocket.request(1);
     return null;
        パラメータ:
        webSocket - WebSocket
        message - メッセージ
        戻り値:
        メッセージ処理が完了したときに完了するCompletionStage。すでに完了している場合はnull

      • onClose

        default CompletionStage<?> onClose​(WebSocket webSocket,
                                   int statusCode,
                                   String reason)
        Closeメッセージを受信します。

        Closeメッセージは、ステータス・コードと終了理由で構成されています。 ステータス・コードは、1000 <= code <= 65535の範囲の整数です。 reasonは、123バイトよりも長くないUTF-8表現を持つ短い文字列です。 Closeメッセージ、ステータス・コード、および理由の詳細については、RFC 6455のセクション「5.5.1。閉じる」と「7.4。ステータス・コード」を参照してください。

        返されたCompletionStageが(通常または例外的に)を完了すると、WebSocketは、適切なCloseメッセージで返信することによって、閉じたハンドシェイクを完了します。

        この実装は、このメッセージと同じコードを持ち、空の理由があるCloseメッセージで応答します。

        onCloseは、Listenerの最後の呼び出しです。 多くても1回だけ呼び出されますが、onOpenの後に呼び出されます。 このメソッドから例外がスローされた場合、それは無視されます。

        WebSocketは、返されたCompletionStageの完了の最も早い時点で閉じるか、Closeメッセージを送信します。 特に、Closeメッセージがsent beforeであった場合、この呼び出しは終了ハンドシェイクを完了し、このメソッドが呼び出されるまでに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メソッドです。 多くても1回だけですが、onOpenの後に呼び出されます。 このメソッドから例外がスローされた場合、それは無視されます。

        WebSocketプロトコルには、着信先で発生するsomeエラーが接続に致命的である必要があることに注意してください。 そのような場合、実装はWebSocket接続の失敗を処理: onErrorが呼び出されるときまでに、 WebSocketは閉じられています。 未処理またはそれ以降の送信操作は、例外的にIOExceptionで完了します。 WebSocket接続の失敗の詳細については、RFC 6455のセクション「7.1.7。WebSocket接続に失敗」を参照してください。

        APIの注:
        メッセージの送信に関連するエラーは、このメソッドではなく、CompletableFuture s sendXメソッドに返されます。
        実装要件:
        このメソッドのデフォルト実装では何の処理も行われません。
        パラメータ:
        webSocket - WebSocket
        error - エラー