- 含まれているインタフェース:
- WebSocket
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<?>
WebSocket入力が閉じられたことを示すクローズ・メッセージを受け取ります。default void
エラーが発生したことを示す。default void
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
- データが受信されたWebSocketdata
- データ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
- データが受信されたWebSocketdata
- データ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
- メッセージが受信されたWebSocketmessage
- メッセージ- 戻り値:
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
- メッセージが受信されたWebSocketmessage
- メッセージ- 戻り値:
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
- メッセージが受信されたWebSocketstatusCode
- ステータス・コードreason
- 理由- 戻り値:
WebSocket
が閉じられたときに完了するCompletionStage
。すぐに閉じられる場合はnull
-
onError
エラーが発生したことを示す。これは、指定されたWebSocketからの最後の起動です。 この呼出しがWebSocket入力を開始するまで、出力はクローズされます。 WebSocketは、WebSocketから呼出しがリクエストされたかどうかにかかわらず、
onOpen
を呼び出した後はいつでも、関連付けられているリスナー上でこのメソッドを呼び出すことができます。このメソッドから例外がスローされた場合、結果の動作は未定義です。
- パラメータ:
webSocket
- エラーが発生したWebSocketerror
- エラー
-