-
public interface WebSocket
WebSocketクライアント。WebSocket
インスタンスはWebSocket.Builder
を介して作成されます。WebSocketには、入力と出力の側があります。 これらの側面は相互に独立しています。 サイドはオープンまたはクローズのいずれかです。 終了すると、サイドはクローズされたままとなります。 WebSocketメッセージは
WebSocket
を介して送信され、関連付けられたWebSocket.Listener
を介して受信されます。 メッセージは、WebSocket出力が閉じられるまで送信され、WebSocket入力が閉じられるまで受信されます。Sendメソッドは、
sendText
、sendBinary
、sendPing
、sendPong
、sendPong
およびsendClose
のメソッドのいずれかです。 送信メソッドは送信操作を開始し、操作が完了すると完了するCompletableFuture
を返します。CompletableFuture
が正常に完了すると、操作は成功したとみなされます。CompletableFuture
が例外的に完了した場合、操作は失敗したとみなされます。 開始されたが完了していない操作は保留中とみなされます。Receiveメソッドは、
onText
、onBinary
、onPing
、onPong
、onPong
およびonClose
のメソッドのいずれかです。 WebSocketは、リスナーの受信メソッドを起動することで受信操作を開始します。 その後、リスナーは操作が完了すると完了するCompletionStage
を返す必要があります。メッセージの受信を制御するために、WebSocketは「内部カウンタ」を保守します。 このカウンタ値は、WebSocketがreceiveメソッドをまだ呼び出していない回数です。 このカウンタはゼロですが、WebSocketは受信メソッドを呼び出しません。
request(n)
が呼び出されると、カウンタはn
ごとに増分されます。 WebSocketが受信メソッドを呼び出すと、カウンタは1だけ減分されます。onOpen
とonError
はメソッドを受け取りません。 WebSocketは、リスナー上の他のメソッドより前にonOpen
を呼び出します。 WebSocketはonOpen
を最大で1回呼び出します。 WebSocketはいつでもonError
を呼び出すことができます。 WebSocketがonError
またはonClose
を呼び出すと、カウンタの値にかかわらず、それ以上のリスナー・メソッドは起動されません。 新しく作成されたWebSocketの場合、カウンタはゼロになります。特に指定がない限り、
null
の引数はWebSocket
のメソッドでNullPointerException
をスローします。同様に、WebSocket
はnull
の引数をListener
のメソッドに渡しません。 WebSocketの状態は、NullPointerException
の1つで完了するNullPointerException
、IllegalArgumentException
、IllegalStateException
のいずれかをスローまたは返す起動によって変更されません。WebSocket
は、PongメッセージとCloseメッセージを返信することで、受信したPingメッセージとCloseメッセージを自動的に処理します。 リスナーがPingまたはCloseメッセージを受信した場合、リスナーからの必須アクションは必要ありません。- APIに関するノート:
- WebSocketとそれに関連するリスナーとの関係は、サブスクリプションと、
Flow
タイプに関連付けられたサブスクライバの関係に似ています。 - 導入されたバージョン:
- 11
-
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 インタフェース 説明 static interface
WebSocket.Builder
「WebSocketクライアント」のビルダー。static interface
WebSocket.Listener
WebSocket
の受信インタフェース。
-
フィールドのサマリー
フィールド 修飾子と型 フィールド 説明 static int
NORMAL_CLOSURE
WebSocket Closeメッセージのステータス・コード(1000
)は、正常終了を示します。これは、接続が確立された目的が達成されたことを意味します。
-
メソッドのサマリー
すべてのメソッド インスタンス・メソッド 抽象メソッド 修飾子と型 メソッド 説明 void
abort()
このWebSocketの入力と出力を突然閉じます。String
getSubprotocol()
このWebSocketが使用するサブ・ブロックを返します。boolean
isInputClosed()
このWebSocket入力がクローズされているかどうかを判断します。boolean
isOutputClosed()
このWebSocket出力が閉じられているかどうかを判断します。void
request(long n)
受信メソッド呼出しのカウンタを増分します。CompletableFuture<WebSocket>
sendBinary(ByteBuffer data, boolean last)
指定されたバッファのバイトとともにバイナリ・データを送信します。CompletableFuture<WebSocket>
sendClose(int statusCode, String reason)
指定されたステータス・コードおよび理由でCloseメッセージを送信することで、このWebSocket出力の正しいクローズを開始します。CompletableFuture<WebSocket>
sendPing(ByteBuffer message)
指定されたバッファのバイトとともにpingメッセージを送信します。CompletableFuture<WebSocket>
sendPong(ByteBuffer message)
指定されたバッファからバイトを含むPongメッセージを送信します。CompletableFuture<WebSocket>
sendText(CharSequence data, boolean last)
指定された文字シーケンスの文字を含むテキスト・データを送信します。
-
-
-
メソッドの詳細
-
sendText
CompletableFuture<WebSocket> sendText(CharSequence data, boolean last)
指定された文字シーケンスの文字を含むテキスト・データを送信します。このメソッドから返された
CompletableFuture
が完了するまで、文字シーケンスを変更しないでください。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalStateException
- 保留中のテキストやバイナリ送信操作がある場合、または前のバイナリ・データでメッセージが完成していない場合 -
IOException
- I/Oエラーが発生した場合、または出力が閉じられている場合
- 実装上のノート:
data
の形式が不正なUTF-16シーケンスである場合、操作はIOException
で失敗します。- パラメータ:
data
- データlast
- この呼出しによってメッセージが完了するとtrue
、それ以外の場合はfalse
- 戻り値:
- データが送信されたときにこのWebSocketを使用して完了した
CompletableFuture
-
-
sendBinary
CompletableFuture<WebSocket> sendBinary(ByteBuffer data, boolean last)
指定されたバッファのバイトとともにバイナリ・データを送信します。データは、バッファ位置からその制限までのバイト数で示されます。 このメソッドから返された
CompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalStateException
- 保留中のテキストやバイナリ送信操作がある場合、または前のテキスト・データでメッセージが完成していない場合 -
IOException
- I/Oエラーが発生した場合、または出力が閉じられている場合
- パラメータ:
data
- データlast
- この呼出しによってメッセージが完了するとtrue
、それ以外の場合はfalse
- 戻り値:
- データが送信されたときにこのWebSocketを使用して完了した
CompletableFuture
-
-
sendPing
CompletableFuture<WebSocket> sendPing(ByteBuffer message)
指定されたバッファのバイトとともにpingメッセージを送信します。メッセージは、バッファ位置からその限界までの
125
バイト以下で構成されます。 このメソッドから返されたCompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalStateException
- 保留中のpingまたは送信操作があるかどうか -
IllegalArgumentException
- メッセージが長すぎる場合 -
IOException
- I/Oエラーが発生した場合、または出力が閉じられている場合
- パラメータ:
message
- メッセージ- 戻り値:
- pingメッセージが送信されたときに、このWebSocketを使用して完了した
CompletableFuture
-
-
sendPong
CompletableFuture<WebSocket> sendPong(ByteBuffer message)
指定されたバッファからバイトを含むPongメッセージを送信します。メッセージは、バッファ位置からその限界までの
125
バイト以下で構成されます。 このメソッドから返されたCompletableFuture
が正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。WebSocket実装では、pingを受信したときに相互的な位置が自動的に送信されるため、メッセージを明示的に送信する必要はほとんどありません。
このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalStateException
- 保留中のpingまたは送信操作があるかどうか -
IllegalArgumentException
- メッセージが長すぎる場合 -
IOException
- I/Oエラーが発生した場合、または出力が閉じられている場合
- パラメータ:
message
- メッセージ- 戻り値:
- pongメッセージが送信されたときに、このWebSocketを使用して完了した
CompletableFuture
-
-
sendClose
CompletableFuture<WebSocket> sendClose(int statusCode, String reason)
指定されたステータス・コードおよび理由でCloseメッセージを送信することで、このWebSocket出力の正しいクローズを開始します。statusCode
は、範囲1000 <= code <= 4999
の整数です。 ステータス・コード1002
、1003
、1006
、1007
、1009
、1010
、1012
、1013
および1015
は不正です。 他のステータス・コードに関する動作は実装固有です。 適切なreason
は、UTF-8表現が123
バイトより長くなっていない文字列です。このメソッドから返された
CompletableFuture
は、次のように例外的に完了できます:-
IllegalArgumentException
-statusCode
が不正な場合、またはreason
が不正な場合 -
IOException
- I/Oエラーが発生した場合、または出力が閉じられている場合
このメソッドから戻された
IllegalArgumentException
がIllegalArgumentException
で完了したり、メソッドがNullPointerException
をスローしないかぎり、出力は閉じられます。まだクローズしていない場合、クローズ・メッセージreceivedまたは
abort
が呼び出されるか、「エラー」が発生するまで、入力は開いたままです。- APIに関するノート:
- 通常は、指定された整数定数
NORMAL_CLOSURE
をステータス・コードとして、空の文字列を理由として使用します。CompletableFuture<WebSocket> webSocket = ... webSocket.thenCompose(ws -> ws.sendText("Hello, ", false)) .thenCompose(ws -> ws.sendText("world!", true)) .thenCompose(ws -> ws.sendClose(WebSocket.NORMAL_CLOSURE, "")) .join();
sendClose
メソッドは、このWebSocket入力を閉じません。 単に、Closeメッセージを送信してこのWebSocket出力を閉じます。 入力の終了を強制するには、abort
メソッドを呼び出します。 次に、Closeメッセージを送信してタイマーを起動するアプリケーションの例を示します。 指定されたタイムアウト内にデータが受信されないと、タイマーは消え、WebSocket
がアラームによって中断されます。MyAlarm alarm = new MyAlarm(webSocket::abort); WebSocket.Listener listener = new WebSocket.Listener() { public CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) { alarm.snooze(); ... } ... }; ... Runnable startTimer = () -> { MyTimer idleTimer = new MyTimer(); idleTimer.add(alarm, 30, TimeUnit.SECONDS); }; webSocket.sendClose(WebSocket.NORMAL_CLOSURE, "ok").thenRun(startTimer);
- パラメータ:
statusCode
- ステータス・コードreason
- 理由- 戻り値:
- closeメッセージが送信されたときに、このWebSocketを使用して完了した
CompletableFuture
-
-
request
void request(long n)
受信メソッド呼出しのカウンタを増分します。このWebSocketは、関連付けられているリスナー
onText
、onBinary
、onPing
、onPong
またはonClose
の各メソッドを、(つまり、receiveメソッド)からn
までの回数を増やします。- APIに関するノート:
- このメソッドのパラメータは、このWebSocketから関連付けられているリスナーにリクエストされる呼出しの数であり、メッセージの数ではありません。 1回の起動ではリスナーにメッセージが配信されるが、常に配信されない場合があります。 たとえば、Ping、PongおよびCloseメッセージは、それぞれ
onPing
、onPong
およびonClose
メソッドが1回起動した状態で配信されます。 ただし、onText
メソッドとonBinary
メソッドの1回の呼出しでテキスト・メッセージとバイナリ・メッセージが配信されるかどうかは、これらのメソッドのブール引数(last
)に依存します。last
がfalse
の場合は、呼出しに配信された数よりも多くのメッセージが表示されます。次に、完全なメッセージが蓄積され、結果が処理されるまで、起動を1回に1つずつリクエストするリスナーの例を示します。
WebSocket.Listener listener = new WebSocket.Listener() { StringBuilder text = new StringBuilder(); public CompletionStage<?> onText(WebSocket webSocket, CharSequence message, boolean last) { text.append(message); if (last) { processCompleteTextMessage(text); text = new StringBuilder(); } webSocket.request(1); return null; } ... }
- パラメータ:
n
- 起動数- 例外:
IllegalArgumentException
-n <= 0
の場合
-
getSubprotocol
String getSubprotocol()
このWebSocketが使用するサブ・ブロックを返します。- 戻り値:
- サブグループ、サブグループがない場合は空の文字列
-
isOutputClosed
boolean isOutputClosed()
このWebSocket出力が閉じられているかどうかを判断します。このメソッドが
true
を返した場合、後続の呼び出しでもtrue
が返されます。- 戻り値:
- 閉じている場合は
true
、そうでない場合はfalse
-
isInputClosed
boolean isInputClosed()
このWebSocket入力がクローズされているかどうかを判断します。このメソッドが
true
を返した場合、後続の呼び出しでもtrue
が返されます。- 戻り値:
- 閉じている場合は
true
、そうでない場合はfalse
-
abort
void abort()
このWebSocketの入力と出力を突然閉じます。このメソッドが入力を返す場合、出力は閉じられます。 保留中の送信操作は、
IOException
で失敗します。 後からabort
を起動しても効果はありません。
-
-