モジュール 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

メソッドのサマリー

修飾子と型	メソッド	説明
default CompletionStage<?>	onBinary(WebSocket webSocket, ByteBuffer data, boolean last)	バイナリ・データを受け取りました。
default CompletionStage<?>	onClose(WebSocket webSocket, int statusCode, String reason)	WebSocket入力が閉じられたことを示すクローズ・メッセージを受け取ります。
default void	onError(WebSocket webSocket, Throwable error)	エラーが発生したことを示す。
default void	onOpen(WebSocket webSocket)	WebSocketが接続されています。
default CompletionStage<?>	onPing(WebSocket webSocket, ByteBuffer message)	Pingメッセージを受信しました。
default CompletionStage<?>	onPong(WebSocket webSocket, ByteBuffer message)	Pongメッセージが受信されました。
default CompletionStage<?>	onText(WebSocket webSocket, CharSequence data, boolean last)	テキスト・データを受け取りました。

メソッドの詳細

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 - エラー