クラスHttpExchange

java.lang.Object
com.sun.net.httpserver.HttpExchange
すべての実装されたインタフェース:
Request, AutoCloseable
直系の既知のサブクラス:
HttpsExchange
public abstract class HttpExchange extends Object implements AutoCloseable, Request
このクラスは、一回の交換で、受信するHTTP要求と生成される応答をカプセル化します。 これは、クライアントからの要求の検査と、応答の作成と送信のための方法を提供します。

HttpExchangeの一般的なライフサイクルを次の順序で示します:

  1. getRequestMethod()でコマンドを決定する
  2. getRequestHeaders()を使用して、リクエスト・ヘッダー(必要に応じて)を調べます。
  3. getRequestBody()は、リクエスト本文を読み取るためのInputStreamを返します。 リクエスト本文の読取り後、ストリームは閉じておく必要があります。
  4. getResponseHeaders()で、Content-Lengthを除くすべての応答ヘッダーを設定する
  5. sendResponseHeaders(int,long)で応答ヘッダーを送信する。 次のステップの前に呼び出す必要がある。
  6. getResponseBody()でOutputStreamを取得して、応答本体を送信する。 応答本体が作成済みの場合は、ストリームを閉じて交換を終了する必要がある。
「交換の終了」
交換は、リクエストInputStreamとレスポンスOutputStreamの両方が閉じられると終了します。 OutputStreamをクローズすると、InputStream (まだ閉じていない場合)が暗黙的にクローズされます。 ただし、閉じる前にInputStreamのすべてのデータを使用することをお薦めします。 簡易メソッドclose()はこれらのタスクをすべて実行します。 要求本体のすべてを使用せずに交換を閉じてもエラーではありませんが、基本となるTCP接続を次の交換用に利用できなくなる場合があります。 交換の終了に失敗した場合の結果は定義されていませんが、通常はリソースの解放や再利用に失敗します。

導入されたバージョン:
1.6

  • フィールドのサマリー

    フィールド
    修飾子と型
    フィールド
    説明
    static final long
    RSPBODY_CHUNKED
    レスポンス本文の長さが指定されていないため、チャンク・エンコードされます
    static final long
    RSPBODY_EMPTY
    このレスポンスでレスポンス本文が送信されていません

  • コンストラクタのサマリー

    コンストラクタ
    修飾子
    コンストラクタ
    説明
    protected
    HttpExchange()
    サブクラスが呼び出すためのコンストラクタ。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    abstract void
    close()
    以下を順番に実行してこの交換を終了: まだ閉じていない場合は、リクエストInputStreamを閉じます。
    abstract Object
    getAttribute(String name)
    Filterモジュールは、バンド外通信メカニズムとしてHttpExchangeインスタンスとともに任意のオブジェクトを格納できます。
    abstract HttpContext
    getHttpContext()
    この交換のHttpContextを返します。
    abstract InetSocketAddress
    getLocalAddress()
    要求を受信したローカル・アドレスを返します。
    abstract HttpPrincipal
    getPrincipal()
    この交換を所有するHttpContextにオーセンティケータが設定されている場合、このメソッドは、このHttpExchangeの認証済ユーザーを表すHttpPrincipalを返します。
    abstract String
    getProtocol()
    protocol/majorVersion.minorVersionの形式で要求からのプロトコル文字列を返します。
    abstract InetSocketAddress
    getRemoteAddress()
    この要求を呼び出すリモート・エンティティのアドレスを返します。
    abstract InputStream
    getRequestBody()
    要求本体を読み込むことができるストリームを返します。
    abstract Headers
    getRequestHeaders()
    このリクエストに含められたHTTPヘッダーを含む不変のHeadersを返します。
    abstract String
    getRequestMethod()
    リクエスト・メソッドを返します。
    abstract URI
    getRequestURI()
    リクエストURIを返します。
    abstract OutputStream
    getResponseBody()
    応答本体の書込み先となるストリームを返します。
    abstract int
    getResponseCode()
    応答コードがすでに設定されている場合は、それを返します。
    abstract Headers
    getResponseHeaders()
    HTTPレスポンス・ヘッダーを格納でき、このレスポンスの一部として転送される可変Headersを返します。
    abstract void
    sendResponseHeaders(int rCode, long responseLength)
    応答ヘッダーと数値の応答コードの現在のセットをこのメソッドの指定どおりに使用して、クライアントへの応答の送返しを開始します。
    abstract void
    setAttribute(String name, Object value)
    Filterモジュールは、バンド外通信メカニズムとしてHttpExchangeインスタンスとともに任意のオブジェクトを格納できます。
    abstract void
    setStreams(InputStream i, OutputStream o)
    「フィルタ」がこの交換InputStreamおよびOutputStreamの(またはその両方)を、指定されたフィルタリングされたストリームとともにラップするために使用します。これにより、getRequestBody()への後続の呼出しは指定されたInputStreamを返し、getResponseBody()への呼出しは指定されたOutputStreamを返します。

    クラスオブジェクトで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    修飾子と型
    メソッド
    説明
    protected Object
    clone()
    このオブジェクトのコピーを作成して、返します。
    boolean
    equals(Object obj)
    このオブジェクトと他のオブジェクトが等しいかどうかを示します。
    protected void
    finalize()
    削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
    最終決定は非推奨であり、将来のリリースで削除される可能性があります。
    final Class<?>
    getClass()
    このObjectの実行時クラスを返します。
    int
    hashCode()
    このオブジェクトに対するハッシュ・コード値を返します。
    final void
    notify()
    このオブジェクトのモニターで待機中のスレッドを1つ再開します。
    final void
    notifyAll()
    このオブジェクトのモニターで待機中のすべてのスレッドを再開します。
    String
    toString()
    オブジェクトの文字列表現を返します。
    final void
    wait()
    現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。
    final void
    wait(long timeoutMillis)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。
    final void
    wait(long timeoutMillis, int nanos)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

    インタフェースRequestで宣言されたメソッド

    with
    修飾子と型
    メソッド
    説明
    default Request
    with(String headerName, List<String> headerValues)
    追加のヘッダーを持つ同一のRequestを返します。

  • フィールド詳細

  • コンストラクタの詳細

    • HttpExchange

      protected HttpExchange()
      サブクラスが呼び出すためのコンストラクタ。

  • メソッドの詳細

    • getRequestHeaders

      public abstract Headers getRequestHeaders()
      このリクエストに含められたHTTPヘッダーを含む不変のHeadersを返します。

      このHeadersのキーはヘッダー名ですが、値は「文字列」のListで、リクエストに含まれる各値を含む順序で含まれます。 複数回表示されるヘッダー・フィールドは、複数の文字列値として表されます。

      Headersのキーでは、大文字と小文字は区別されません。

      定義:
      インタフェースRequest内のgetRequestHeaders
      戻り値:
      リクエスト・ヘッダーへのアクセスに使用できる読取り専用Headers。

    • getResponseHeaders

      public abstract Headers getResponseHeaders()
      HTTPレスポンス・ヘッダーを格納でき、このレスポンスの一部として転送される可変Headersを返します。

      Headersのキーはヘッダー名で、値は(含める順序)を複数回含める必要がある各値を含む「文字列」のListである必要があります。

      Headersのキーでは、大文字と小文字は区別されません。

      戻り値:
      レスポンス・ヘッダーの設定に使用できる書込み可能なHeaders。

    • getRequestURI

      public abstract URI getRequestURI()
      リクエストURIを返します。
      定義:
      インタフェースRequest内のgetRequestURI
      戻り値:
      リクエストURI

    • getRequestMethod

      public abstract String getRequestMethod()
      リクエスト・メソッドを返します。
      定義:
      インタフェースRequest内のgetRequestMethod
      戻り値:
      リクエスト・メソッド文字列

    • getHttpContext

      public abstract HttpContext getHttpContext()
      この交換のHttpContextを返します。
      戻り値:
      the HttpContext

    • close

      public abstract void close()
      次の順序どおりに実行することで、この交換を終了します。
      1. まだ閉じていない場合は、リクエストInputStreamを閉じます。
      2. まだ閉じていない場合は、レスポンスOutputStreamを閉じます。
      定義:
      close、インタフェースAutoCloseable

    • getRequestBody

      public abstract InputStream getRequestBody()
      要求本体を読み込むことができるストリームを返します。 このメソッドを複数回呼び出した場合でも、同じストリームが返されます。 閉じる前に、このストリームからのすべてのデータをアプリケーションで使用する(読み取る)ことをお勧めします。 すべてのデータが読み取られる前にストリームがクローズされた場合、InputStream.close()コールは残りのデータ(実装固有のバイト数まで)を読み取り、破棄します。
      戻り値:
      要求本体を読み取ることができるストリーム

    • getResponseBody

      public abstract OutputStream getResponseBody()
      レスポンス本文を書き込む必要があるストリームを返します。sendResponseHeaders(int,long))は、このメソッドをコールする前にコールする必要があります。 同一の交換用にこのメソッドを複数回呼び出した場合でも、同じストリームが返されます。 それぞれの交換を正しく終了させるためには、応答本体を送信しない場合でも、出力ストリームを閉じる必要があります。

      このストリームをクローズすると、getRequestBody() (まだ閉じていない場合)から返されたInputStreamが暗黙的にクローズされます。

      sendResponseHeaders(int, long)へのコールでレスポンス本文の固定長が指定されている場合は、そのコールで指定された正確なバイト数をこのストリームに書き込む必要があります。 書き込まれるバイトが多すぎる場合、OutputStreamのwriteメソッドはIOExceptionをスローします。 書き込まれるバイトが少なすぎる場合、ストリームOutputStream.close()はIOExceptionをスローします。 どちらの場合も、交換は中止され、基本となるTCP接続は閉じられます。

      戻り値:
      応答本体の書込み先のストリーム

    • sendResponseHeaders

      public abstract void sendResponseHeaders(int rCode, long responseLength) throws IOException
      応答ヘッダーと数値の応答コードの現在のセットをこのメソッドの指定どおりに使用して、クライアントへの応答の送返しを開始します。 応答本体の長さも、次のように指定されます。 レスポンス長パラメータがzeroより大きい場合は、送信する正確なバイト数を指定し、アプリケーションはその正確な量のデータを送信する必要があります。 レスポンス長パラメータの値がRSPBODY_CHUNKED (ゼロ)の場合、レスポンス本文はチャンク転送エンコーディングを使用し、任意の量のデータを送信できます。 アプリケーションは、OutputStreamを閉じてレスポンス本文を終了します。 レスポンスの長さの値がRSPBODY_EMPTYの場合、レスポンス本文は送信されません。

      Content-Length応答ヘッダーがまだ設定されていない場合は、応答の長さパラメータに応じて適切な値に設定されます。

      このメソッドは、getResponseBody()を呼び出す前に呼び出す必要があります。

      APIのノート:
      レスポンス本文をバイト配列から送信し、配列の長さをresponseLengthパラメータとして使用する場合は、配列が空の場合の動作に注意してください。 この場合、responseLengthはゼロになります。これは、長さがゼロになるRSPBODY_CHUNKEDの値ですが、チャンク化されたエンコードされたレスポンス本体になります。 これは正しくありませんが、空の配列をチェックし、かわりにresponseLengthをRSPBODY_EMPTYに設定することをお薦めします。 また、チャンク化されたエンコードされたレスポンス本文を送信する場合、長さに関係なく、出力ストリームはハンドラによって明示的に閉じられる必要があります。
      実装上のノート:
      この実装によって、コール元は、交換終了後にConnection: closeヘッダーを「レスポンス・ヘッダー」に提供して、sendResponseHeadersの呼出し前に接続を強制的にクローズするようにサーバーに指示できます。
      パラメータ:
      rCode - 送信する応答コード
      responseLength - 0より大きい場合、固定レスポンス本文長を指定し、getResponseCode()から取得したストリームに正確なバイト数を書き込む必要があります。RSPBODY_CHUNKEDと等しい場合、チャンク化されたエンコーディングが使用され、任意のバイト数が書き込まれる可能性があります。 RSPBODY_EMPTYと等しい場合、レスポンス本文の長さは指定されず、レスポンス本文は書き込まれません。 -1以下の値は、RSPBODY_EMPTYと同じように扱われます。
      スロー:
      IOException - レスポンス・ヘッダーがすでに送信されている場合、またはI/Oエラーが発生した場合
      関連項目:

    • getRemoteAddress

      public abstract InetSocketAddress getRemoteAddress()
      この要求を呼び出すリモート・エンティティのアドレスを返します。
      戻り値:
      呼出し側のInetSocketAddress

    • getResponseCode

      public abstract int getResponseCode()
      応答コードがすでに設定されている場合は、それを返します。
      戻り値:
      使用可能な場合は、応答コード。まだ使用可能でない場合は、-1。

    • getLocalAddress

      public abstract InetSocketAddress getLocalAddress()
      要求を受信したローカル・アドレスを返します。
      戻り値:
      ローカル・インタフェースのInetSocketAddress

    • getProtocol

      public abstract String getProtocol()
      protocol/majorVersion.minorVersionの形式で要求からのプロトコル文字列を返します。 たとえば、"HTTP/1.1"などです。
      戻り値:
      要求からのプロトコル文字列

    • getAttribute

      public abstract Object getAttribute(String name)
      Filterモジュールは、バンド外通信メカニズムとしてHttpExchangeインスタンスとともに任意のオブジェクトを格納できます。 その後、他のフィルタまたは交換ハンドラがこれらのオブジェクトにアクセスできます。

      各Filterクラスは、使用可能にする属性をドキュメント化します。

      パラメータ:
      name - 取得する属性の名前
      戻り値:
      属性オブジェクト。存在しない場合はnull
      スロー:
      NullPointerException - nameがnullの場合

    • setAttribute

      public abstract void setAttribute(String name, Object value)
      Filterモジュールは、バンド外通信メカニズムとしてHttpExchangeインスタンスとともに任意のオブジェクトを格納できます。 その後、他のフィルタまたは交換ハンドラがこれらのオブジェクトにアクセスできます。

      各Filterクラスは、使用可能にする属性をドキュメント化します。

      パラメータ:
      name - 属性値に関連付ける名前
      value - 属性値として格納するオブジェクト。null値が許可される。
      スロー:
      NullPointerException - nameがnullの場合

    • setStreams

      public abstract void setStreams(InputStream i, OutputStream o)
      「フィルタ」がこの交換InputStreamおよびOutputStreamの(またはその両方)を、指定されたフィルタリングされたストリームとともにラップするために使用します。これにより、getRequestBody()への後続の呼出しは指定されたInputStreamを返し、getResponseBody()への呼出しは指定されたOutputStreamを返します。 このコールに提供されるストリームは、元のストリームをラップする必要があり、FilterInputStreamおよびFilterOutputStreamの(ただし、必須ではありません)サブクラスです。
      パラメータ:
      i - このオブジェクトInputstreamとして設定する、フィルタ処理された入力ストリーム。変更がない場合はnull
      o - このオブジェクトOutputstreamとして設定する、フィルタ処理された出力ストリーム。変更がない場合はnull

    • getPrincipal

      public abstract HttpPrincipal getPrincipal()
      この交換を所有するHttpContextにオーセンティケータが設定されている場合、このメソッドは、このHttpExchangeの認証済ユーザーを表すHttpPrincipalを返します。
      戻り値:
      HttpPrincipal、またはオーセンティケータが設定されていない場合はnull