モジュール java.net.http
パッケージ java.net.http

インタフェースWebSocket.Listener

含まれているインタフェース:
WebSocket
public static interface WebSocket.Listener
WebSocketの受信インタフェース。

WebSocketは、関連付けられたリスナーのメソッドを呼び出し、それ自体を引数として渡します。 これらのメソッドはスレッド・セーフな方法で起動されるため、次の起動は前のメソッドの起動が終了した後でのみ開始できます。

データが受信されると、WebSocketはreceiveメソッドを呼び出します。 メソッドonText、onBinary、onPingおよびonPongは、リスナーがメッセージを受信した後に完了したCompletionStageを返す必要があります。 リスナー・メソッドがCompletionStageではなくnullを戻す場合、WebSocketは、リスナーがすでに正常に完了したCompletionStageを戻したかのように動作します。

WebSocketでIOExceptionが発生すると、(入力が閉じていない場合)という例外を持つonErrorが呼び出されます。 特に指定しないかぎり、リスナー・メソッドが例外をスローし、メソッドによってメソッドからスローされた例外がスローされた場合、WebSocketは、この例外が発生しても例外をスローします。

APIのノート:
WebSocketからListenerへの呼出し順序は、特にListenerメソッドが不入として処理されることを意味します。 これは、Listener実装が、可能な再帰、または処理ロジックに関してWebSocket.requestを呼び出す順序に関係する必要がないことを意味します。

リスナーが複数のWebSocketに関連付けられている場合は注意が必要です。 この場合、WebSocketの異なるインスタンスに関連する呼出しは順序付けされず、同時に発生する可能性があります。

受信メソッドから返されたCompletionStageには、「呼出しのカウンタ」では何もできません。 つまり、リスナー・メソッドの呼出し数を増やすために、CompletionStageを完了する必要はありません。 次の例は、完全なメッセージが蓄積されてから、結果が処理され、CompletionStageが完了するまでの間の起動のリクエストを一度に1つずつ行います。 

    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が接続されています。

      これは最初の起動で、1回行われます。 これは、通常、起動を増やすためのリクエストを作成するために使用されます。

      実装要件:
      デフォルトの実装は次のものと同等です。 
          webSocket.request(1);
      パラメータ:
      webSocket - 接続されているWebSocket

    • onText

      default CompletionStage<?> onText​(WebSocket webSocket, CharSequence data, boolean last)
      テキスト・データを受け取りました。

      WebSocketがCharSequenceを再生する可能性があることを示すために、WebSocketが使用するCompletionStageを返します。 このCompletionStageが完了した後はCharSequenceにアクセスしないでください。

      実装要件:
      デフォルトの実装は次のものと同等です。 
          webSocket.request(1);
    return null;
      実装上のノート:
      dataは常に正当なUTF-16シーケンスです。
      パラメータ:
      webSocket - データが受信されたWebSocket
      data - データ
      last - この呼出しがメッセージを完了するかどうか
      戻り値:
      CharSequenceが再生されるときに完了するCompletionStage。すぐに回収できる場合はnull

    • onBinary

      default CompletionStage<?> onBinary​(WebSocket webSocket, ByteBuffer data, boolean last)
      バイナリ・データを受け取りました。

      このデータは、バッファ位置からその制限までのバイト数に置かれます。

      WebSocketがByteBufferを再生する可能性があることを示すために、WebSocketが使用するCompletionStageを返します。 このCompletionStageが完了した後はByteBufferにアクセスしないでください。

      実装要件:
      デフォルトの実装は次のものと同等です。 
          webSocket.request(1);
    return null;
      パラメータ:
      webSocket - データが受信されたWebSocket
      data - データ
      last - この呼出しがメッセージを完了するかどうか
      戻り値:
      ByteBufferが再生されるときに完了するCompletionStage。すぐに回収できる場合はnull

    • onPing

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

      WebSocketプロトコルによって保証されているように、メッセージは125バイトを超えていません。 これらのバイトは、バッファ位置からその制限までです。

      WebSocket実装では、pingを受信したときに双方向ポックが自動的に送信されるため、pingを受信したときにメッセージを明示的に送信する必要はほとんどありません。

      WebSocketによって使用されるCompletionStageをByteBufferを再利用できるシグナルとして返します。 このCompletionStageが完了した後はByteBufferにアクセスしないでください。

      実装要件:
      デフォルトの実装は次のものと同等です。 
          webSocket.request(1);
    return null;
      パラメータ:
      webSocket - メッセージが受信されたWebSocket
      message - メッセージ
      戻り値:
      ByteBufferが再生されるときに完了するCompletionStage。すぐに回収できる場合はnull

    • onPong

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

      WebSocketプロトコルによって保証されているように、メッセージは125バイトを超えていません。 これらのバイトは、バッファ位置からその制限までです。

      WebSocketによって使用されるCompletionStageをByteBufferを再利用できるシグナルとして返します。 このCompletionStageが完了した後はByteBufferにアクセスしないでください。

      実装要件:
      デフォルトの実装は次のものと同等です。 
          webSocket.request(1);
    return null;
      パラメータ:
      webSocket - メッセージが受信されたWebSocket
      message - メッセージ
      戻り値:
      ByteBufferが再生されるときに完了するCompletionStage。すぐに回収できる場合はnull

    • onClose

      default CompletionStage<?> onClose​(WebSocket webSocket, int statusCode, String reason)
      WebSocket入力が閉じられたことを示すクローズ・メッセージを受け取ります。

      これは、指定されたWebSocketからの最後の呼出しです。 この起動が開始されるまでに、WebSocket入力がクローズされます。

      Closeメッセージは、ステータス・コードと終了理由で構成されています。 ステータス・コードは、範囲1000 <= code <= 65535の整数です。 reasonは、UTF-8表現が123バイトより長くなっていない文字列です。

      WebSocketの出力がまだ閉じていない場合、WebSocketの出力が閉じられる可能性があることを示すために、このメソッドによって返されたCompletionStageが使用されます。 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 - 理由
      戻り値:
      WebSocketが閉じられたときに完了するCompletionStage。すぐに閉じられる場合はnull

    • onError

      default void onError​(WebSocket webSocket, Throwable error)
      エラーが発生したことを示す。

      これは、指定されたWebSocketからの最後の起動です。 この呼出しがWebSocket入力を開始するまで、出力はクローズされます。 WebSocketは、WebSocketから呼出しがリクエストされたかどうかにかかわらず、onOpenを呼び出した後はいつでも、関連付けられているリスナー上でこのメソッドを呼び出すことができます。

      このメソッドから例外がスローされた場合、結果の動作は未定義です。

      パラメータ:
      webSocket - エラーが発生したWebSocket
      error - エラー