モジュール java.net.http
パッケージ java.net.http

インタフェースWebSocket

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は、次のように例外的に完了できます:

      パラメータ:
      message - メッセージ
      戻り値:
      pingメッセージが送信されたときに、このWebSocketを使用して完了したCompletableFuture

    • sendPong

      CompletableFuture<WebSocket> sendPong​(ByteBuffer message)
      指定されたバッファからバイトを含むPongメッセージを送信します。

      メッセージは、バッファ位置からその限界までの125バイト以下で構成されます。 このメソッドから返されたCompletableFutureが正常に終了すると、バッファには残りのバイトがありません。 それ以降はバッファにアクセスしてはなりません。

      WebSocket実装では、pingを受信したときに相互的な位置が自動的に送信されるため、メッセージを明示的に送信する必要はほとんどありません。

      このメソッドから返されたCompletableFutureは、次のように例外的に完了できます:

      パラメータ:
      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を起動しても効果はありません。