-
- 含まれているインタフェース:
- 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
-
-
メソッドのサマリー
すべてのメソッド インスタンス・メソッド デフォルト・メソッド 修飾子と型 メソッド 説明 default CompletionStage<?>
onBinary(WebSocket webSocket, ByteBuffer message, WebSocket.MessagePart part)
バイナリ・メッセージを受信します。default CompletionStage<?>
onClose(WebSocket webSocket, int statusCode, String reason)
Closeメッセージを受信します。default void
onError(WebSocket webSocket, Throwable error)
I/Oまたはプロトコル・エラーが発生したことを通知します。default void
onOpen(WebSocket webSocket)
提供されたWebSocket
に接続されていることをListener
に通知します。default CompletionStage<?>
onPing(WebSocket webSocket, ByteBuffer message)
PINGメッセージを受信します。default CompletionStage<?>
onPong(WebSocket webSocket, ByteBuffer message)
Pongメッセージを受信します。default CompletionStage<?>
onText(WebSocket webSocket, CharSequence message, WebSocket.MessagePart part)
テキスト・メッセージを受信します。
-
-
-
メソッドの詳細
-
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
- WebSocketmessage
- メッセージ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
- WebSocketmessage
- メッセージ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
- WebSocketmessage
- メッセージ- 戻り値:
- メッセージ処理が完了したときに完了する
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
- WebSocketmessage
- メッセージ- 戻り値:
- メッセージ処理が完了したときに完了する
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
- WebSocketstatusCode
- ステータス・コード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
ssendX
メソッドに返されます。 - 実装要件:
- このメソッドのデフォルト実装では何の処理も行われません。
- パラメータ:
webSocket
- WebSocketerror
- エラー
-
-