パッケージ jakarta.websocket

インターフェース RemoteEndpoint

  • 既知のすべてのサブインターフェース:
    RemoteEndpoint.Async, RemoteEndpoint.Basic
    public interface RemoteEndpoint
    RemoteEndpoint オブジェクトはコンテナーによって提供され、Web ソケット会話の「もう一方の端」またはピアを表します。RemoteEndpoint のインスタンスは、Session.getBasicRemote() または Session.getAsyncRemote() を使用してセッションから取得されます。この種のオブジェクトには、Web ソケットメッセージを送信するためのさまざまな方法が含まれています。RemoteEndpoint オブジェクトには、WebSocket メッセージを同期送信するための RemoteEndpoint.Basic と、メッセージを非同期に送信するための RemoteEndpoint.Async の 2 種類があります。

    ピアへの Web ソケットメッセージの正常な配信の保証はありませんが、メッセージを送信するアクションによってコンテナーに認識されているエラーが発生した場合、API はそれをスローします。RemoteEndpoints には、メッセージを送信するためのさまざまな方法が含まれています。メッセージ全体、部分、WebSocket の ping や pong を含むさまざまなデータ形式です。

    実装は、メッセージのバッチ処理をサポートする場合とサポートしない場合があります。バッチ処理をサポートする実装の予想されるセマンティクスの詳細は、setBatchingAllowed(boolean) に記載されています。

    メモ: 実装では、大きなメッセージを小さな部分で送信するための独自のスキームを選択できます。これらのスキームは、メッセージが最終的にネットワーク上で送信される基盤となる WebSocket データフレームと関連がある場合とない場合があります。

    基礎となる接続が閉じられ、RemoteEndpoint のメソッドが呼び出されようとすると、エラーが生成されます。メッセージを送信するメソッドの場合、これは IOException になり、エンドポイントの構成を変更するメソッドの場合、これはランタイム IllegalArgumentExceptions になります。

    作成者:
    dannycoward

    • ネストされたクラスの概要

      ネストされたクラス  
      修飾子と型 インターフェース 説明
      static interface RemoteEndpoint.Async
      Web ソケット会話のピアのこの表現には、メッセージを非同期的に送信する機能があります。
      static interface RemoteEndpoint.Basic
      Web ソケット会話のピアのこの表現には、メッセージを同期的に送信する機能があります。

    • 方法の概要

      すべてのメソッド   インスタンスメソッド   抽象メソッド  
      修飾子と型 メソッド 説明
      voidflushBatch()
      この方法は、この RemoteEndpint でバッチ処理が許可されている場合にのみ使用されます。
      booleangetBatchingAllowed()
      実装が送信前に送信メッセージをバッチ処理できるかどうかを返します。
      voidsendPing​(ByteBufferSE applicationData)
      指定されたアプリケーションデータを含む Ping メッセージをリモートエンドポイントに送信します。
      voidsendPong​(ByteBufferSE applicationData)
      開発者が、セッションの単方向ハートビートとして機能するために、指定されたアプリケーションデータを含む一方的な Pong メッセージを送信できるようにします。
      voidsetBatchingAllowed​(boolean allowed)
      送信する前に送信メッセージをバッチ処理できることを実装に示します。

    • メソッドの詳細

      • setBatchingAllowed

        void setBatchingAllowed​(boolean allowed)
                 throws IOExceptionSE
        送信する前に送信メッセージをバッチ処理できることを実装に示します。すべての実装が送信メッセージのバッチ処理をサポートしているわけではありません。RemoteEndpoints のデフォルトモードは false です。開発者が送信メッセージのバッチ処理が許可されていることを示した場合、開発者は flushBatch() を呼び出して、この RemoteEndpoint の send メソッドに渡されたすべてのメッセージが確実に送信されるようにする必要があります。バッチ処理が許可されている場合、メッセージがローカルバッチに書き込まれていれば、実装の送信操作は完了したと見なされ、メッセージ用のスペースがまだバッチにある場合は完了したと見なされ、バッチにメッセージを書き込むときにバッチを送信する必要がある場合は、ピアに送信され、残りが新しいバッチに書き込まれます。ブロッキングメソッドと非同期送信メソッドは、ブロッキング呼び出しを完了し、SendHandlers に通知し、Futures を完了するために、この完了の概念を使用します。バッチ処理が許可されている場合、開発者が flushBatch() を呼び出さずにこの RemoteEndpoint の send メソッドを呼び出した場合、実装は開発者が送信を要求したすべてのメッセージを送信していない可能性があります。パラメーター値が false で、実装に未送信メッセージのバッチがある場合、実装はすぐに未送信メッセージのバッチを送信する必要があります。
        パラメーター:
        allowed - 実装がメッセージのバッチ処理を許可されているかどうか。
        例外:
        IOExceptionSE - バッチ処理が無効になっていて未送信のメッセージがある場合、問題があると実装が未送信のメッセージのバッチを送信するため、このエラーがスローされる可能性があります。

      • getBatchingAllowed

        boolean getBatchingAllowed()
        実装が送信前に送信メッセージをバッチ処理できるかどうかを返します。RemoteEndpoints のデフォルトモードは false です。setBatchingAllowed を呼び出すことにより、値を変更できます。
        戻り値:
        実装が送信前に送信メッセージをバッチ処理できる場合は true、それ以外の場合は false

      • flushBatch

        void flushBatch()
         throws IOExceptionSE
        この方法は、この RemoteEndpint でバッチ処理が許可されている場合にのみ使用されます。このメソッドを呼び出すと、実装はバッチ処理されている未送信のメッセージを送信します。
        例外:
        IOExceptionSE - 未送信のメッセージの送信に失敗した場合

      • sendPing

        void sendPing​(ByteBufferSE applicationData)
       throws IOExceptionSE,
              IllegalArgumentExceptionSE
        指定されたアプリケーションデータを含む Ping メッセージをリモートエンドポイントに送信します。対応する Pong メッセージは、MessageHandler.Pong ハンドラーを使用して取得できます。

        このメッセージの送信が完了するまで、他のスレッドが ByteBuffer を使用することは安全ではありません。メッセージの送信が正常に完了すると、バッファーの制限は変更されず、バッファーの位置は制限と等しくなります。メッセージの送信が正常に完了しない場合、バッファの状態は未定義です。

        パラメーター:
        applicationData - ping リクエストで運ばれるデータ。
        例外:
        IOExceptionSE - ping の送信に失敗した場合
        IllegalArgumentExceptionSE - applicationData が最大許容ペイロード 125 バイトを超える場合

      • sendPong

        void sendPong​(ByteBufferSE applicationData)
       throws IOExceptionSE,
              IllegalArgumentExceptionSE
        開発者が、セッションの単方向ハートビートとして機能するために、指定されたアプリケーションデータを含む一方的な Pong メッセージを送信できるようにします。

        このメッセージの送信が完了するまで、他のスレッドが ByteBuffer を使用することは安全ではありません。メッセージの送信が正常に完了すると、バッファーの制限は変更されず、バッファーの位置は制限と等しくなります。メッセージの送信が正常に完了しない場合、バッファの状態は未定義です。

        パラメーター:
        applicationData - ポンレスポンスで運ばれるアプリケーションデータ。
        例外:
        IOExceptionSE - ポンが送信されなかった場合
        IllegalArgumentExceptionSE - applicationData が最大許容ペイロード 125 バイトを超える場合