-
public interface WebSocket
WebSocketクライアント。
インキュベーション機能。将来のリリースで削除されます。WebSocket
を作成するには、HttpClient.newWebSocketBuilder()
メソッドを使用します。WebSocket
を閉じるには、sendClose
またはabort
のいずれかのメソッドを使用します。WebSocketメッセージは、
WebSocket
を介して送信され、WebSocket
Listener
を介して受信されます。 メッセージは、出力が閉じられるまで送信され、入力が閉じられるまで受信されます。 出力と入力の両方が閉じているWebSocket
は、それ自体が閉じられていると考えられます。 これらの状態をチェックするには、isOutputClosed()
とisInputClosed()
を使用します。メッセージを送信するメソッドは、メッセージが送信されると正常に完了する
CompletableFuture
を返します。エラーが発生した場合は例外的に完了します。メッセージを受信するには、まずそれをリクエストします。
n
メッセージがリクエストされた場合、リスナーはWebSocket
から指定されたメソッドのより多くの呼び出しをn
まで受信します。 メッセージをリクエストするには、request(long)
を使用します。 リクエストは加算演算です。つまり、request(n)
に続くrequest(m)
はrequest(n + m)
に相当します。部分的にメッセージを送信または受信する場合、メッセージ全体は、最後の呼び出しが追加のメソッド引数を介して識別される一連の1つ以上の呼び出しとして転送されます。
特に指定がない限り、
null
の引数はWebSocket
のメソッドでNullPointerException
をスローします。同様に、WebSocket
はnull
の引数をListener
のメソッドに渡しません。- 実装要件:
WebSocket
のメソッドは、NullPointerException
、IllegalArgumentException
、およびIllegalStateException
に関して、失敗-アトミックです。 つまり、メソッドが例外をスローするか、返されたCompletableFuture
が例外を指定して例外的に完了すると、WebSocket
はメソッドがまったく呼び出されていないかのように動作します。WebSocket
は、リスナーのメソッドをスレッド・セーフな方法で呼び出します。WebSocket
は、それぞれPongメッセージとCloseメッセージで応答することによって、PingとCloseメッセージを自動的に処理します。 リスナーがPingまたはCloseメッセージを受信した場合、リスナーからの必須アクションは必要ありません。- 導入されたバージョン:
- 9
-
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 インタフェース 説明 static interface
WebSocket.Builder
WebSocket
インスタンスを作成するためのビルダー。static interface
WebSocket.Listener
WebSocket
の受信インタフェース。static class
WebSocket.MessagePart
部分メッセージを識別するためにWebSocket.Listener
によって使用されるマーカー。
-
フィールドのサマリー
フィールド 修飾子と型 フィールド 説明 static int
NORMAL_CLOSURE
WebSocket Closeメッセージのステータス・コード(1000
)は、正常終了を示します。これは、接続が確立された目的が達成されたことを意味します。
-
メソッドのサマリー
すべてのメソッド インスタンス・メソッド 抽象メソッド 修飾子と型 メソッド 説明 void
abort()
このWebSocket
を突然閉じます。String
getSubprotocol()
このWebSocket
のサブ・プロトコルを返します。boolean
isInputClosed()
このWebSocket
がメッセージを受信するために完全に閉じられているかどうかを伝えます。boolean
isOutputClosed()
このWebSocket
がメッセージを送信するために完全に閉じられているかどうかを伝えます。void
request(long n)
このWebSocket
からより多くのメッセージをn
にリクエストします。CompletableFuture<WebSocket>
sendBinary(ByteBuffer message, boolean isLast)
指定されたByteBuffer
からバイナリ・メッセージをバイト数で送信します。CompletableFuture<WebSocket>
sendClose(int statusCode, String reason)
指定されたステータス・コードと理由でCloseメッセージを送信し、正常終了を開始します。CompletableFuture<WebSocket>
sendPing(ByteBuffer message)
指定されたByteBuffer
からバイト数のPingメッセージを送信します。CompletableFuture<WebSocket>
sendPong(ByteBuffer message)
指定されたByteBuffer
のバイトを含むPongメッセージを送信します。CompletableFuture<WebSocket>
sendText(CharSequence message, boolean isLast)
指定されたCharSequence
の文字を含むテキスト・メッセージを送信します。
-
-
-
メソッドの詳細
-
sendText
CompletableFuture<WebSocket> sendText(CharSequence message, boolean isLast)
指定されたCharSequence
の文字を含むテキスト・メッセージを送信します。テキスト・メッセージを送信するには、前のテキストまたはバイナリ・メッセージが送信された後にのみ、このメソッドを呼び出します。 このメソッドから返された
CompletableFuture
が完了するまで、文字シーケンスを変更しないでください。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalArgumentException
-message
が不正な形式のUTF-16シーケンスの場合 -
IllegalStateException
-sendClose
が呼び出された場合、または前のメッセージがまだ送信されていない場合、または以前のバイナリ・メッセージがisLast == false
で送信された場合 -
IOException
- I/Oエラーが発生した場合
- 実装上の注意:
- 部分的なUTF-16シーケンスがこのメソッドに渡された場合、返される
CompletableFuture
は例外的にIOException
で完了します。 - パラメータ:
message
- メッセージisLast
-true
メッセージの最後の部分であればfalse
、そうでなければfalse
- 戻り値:
- この
WebSocket
で、メッセージが送信されたときに完了するCompletableFuture
-
-
sendBinary
CompletableFuture<WebSocket> sendBinary(ByteBuffer message, boolean isLast)
指定されたByteBuffer
からバイナリ・メッセージをバイト数で送信します。バイナリ・メッセージを送信するには、前のテキストまたはバイナリ・メッセージが送信された後にのみ、このメソッドを呼び出します。 メッセージは、バッファ位置からその限界までのバイトで構成されます。 このメソッドから返された
CompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalStateException
-sendClose
が呼び出された場合、または前のメッセージがまだ送信されていない場合、またはisLast == false
で前のテキスト・メッセージが送信された場合 -
IOException
- I/Oエラーが発生した場合
- パラメータ:
message
- メッセージisLast
-true
メッセージの最後の部分であればfalse
、そうでなければfalse
- 戻り値:
- この
WebSocket
で、メッセージが送信されたときに完了するCompletableFuture
-
-
sendPing
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
指定されたByteBuffer
からバイト数のPingメッセージを送信します。メッセージは、バッファ位置からその限界までの
125
バイト以下で構成されます。 このメソッドから返されたCompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalArgumentException
- メッセージが長すぎる場合 -
IllegalStateException
-sendClose
が呼び出された場合 -
IOException
- I/Oエラーが発生した場合
- パラメータ:
message
- メッセージ- 戻り値:
- Pingメッセージが送信されたときに、この
WebSocket
で完了するCompletableFuture
-
-
sendPong
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
指定されたByteBuffer
のバイトを含むPongメッセージを送信します。メッセージは、バッファ位置からその限界までの
125
バイト以下で構成されます。 このメソッドから返されたCompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalArgumentException
- メッセージが長すぎる場合 -
IllegalStateException
-sendClose
が呼び出された場合 -
IOException
- I/Oエラーが発生した場合
- パラメータ:
message
- メッセージ- 戻り値:
- Pongメッセージが送信されたときに、この
WebSocket
で完了するCompletableFuture
-
-
sendClose
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
指定されたステータス・コードと理由でCloseメッセージを送信し、正常終了を開始します。このメソッドが返すとき、出力は閉じられています。
statusCode
は、範囲1000 <= code <= 4999
の整数です。 ステータス・コード1002
、1003
、1006
、1007
、1009
、1010
、1012
、1013
および1015
は不正です。 他のステータス・コードに関する動作は実装固有です。reason
は、123
バイト以下のUTF-8表現を持つ文字列です。一般的なケースでは、ステータス・コードとして整数定数
NORMAL_CLOSURE
を使用し、理由として空の文字列を使用します。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalArgumentException
-statusCode
またはreason
が不正な場合 -
IOException
- I/Oエラーが発生した場合
- 実装要件:
- Closeメッセージを送信しているエンドポイントは、さまざまな理由により、補完的なCloseメッセージを適時に受信しないことがあります。
WebSocket
実装は、sendClose
メソッドが呼び出されると、Closeフレームが受信されたかどうかにかかわらず、このAPIのユーザーからの介入なしにWebSocket
が終了することを保証するクロージャ・メカニズムを提供する責任があります。 メソッドsendClose
は、おそらく、このAPIのユーザーからの最後の呼び出しであるように設計されています。 - パラメータ:
statusCode
- ステータス・コードreason
- 理由- 戻り値:
- Closeメッセージが送信されたときに、この
WebSocket
で完了するCompletableFuture
-
-
request
void request(long n)
このWebSocket
からより多くのメッセージをn
にリクエストします。この
WebSocket
は、リスナーonText
、onBinary
、onPing
、onPong
またはonClose
メソッドをn
までさらに呼び出します。このメソッドはいつでも呼び出すことができます。
- パラメータ:
n
- リクエストされたメッセージの数- 例外:
IllegalArgumentException
-n <= 0
の場合
-
getSubprotocol
String getSubprotocol()
このWebSocket
のサブ・プロトコルを返します。このメソッドはいつでも呼び出すことができます。
- 戻り値:
- この
WebSocket
のサブ・プロトコル、またはサブ・プロトコルがない場合は空のString
-
isOutputClosed
boolean isOutputClosed()
このWebSocket
がメッセージを送信するために完全に閉じられているかどうかを伝えます。このメソッドが
true
を返した場合、後続の呼び出しでもtrue
が返されます。 このメソッドはいつでも呼び出すことができます。- 戻り値:
- 閉じている場合は
true
、そうでない場合はfalse
-
isInputClosed
boolean isInputClosed()
このWebSocket
がメッセージを受信するために完全に閉じられているかどうかを伝えます。このメソッドが
true
を返した場合、後続の呼び出しでもtrue
が返されます。 このメソッドはいつでも呼び出すことができます。- 戻り値:
- 閉じている場合は
true
、そうでない場合はfalse
-
abort
void abort()
このWebSocket
を突然閉じます。このメソッドが返ると、入力と出力の両方が閉じられます。 このメソッドはいつでも呼び出すことができます。 後続の呼び出しは効果がありません。
- APIの注:
- その実装、状態(例えば、メッセージがその時点で転送されているかどうか)、および関連するリソースの解放中に起こりうるエラーに応じて、この
WebSocket
はリスナーonError
を呼び出すことがあります。
-
-