モジュール jdk.httpserver

パッケージ com.sun.net.httpserver

クラス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

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

コンストラクタ

修飾子	コンストラクタ	説明
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を返します。

クラスjava.lang.Objectで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

インタフェースcom.sun.net.httpserver.Requestで宣言されたメソッド

with

コンストラクタの詳細

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より大きい場合は、送信する正確なバイト数を指定し、アプリケーションはその正確な量のデータを送信する必要があります。 応答の長さパラメータがzeroの場合は、チャンク転送エンコーディングが使用され、任意のデータ量を送信できます。 アプリケーションは、OutputStreamを閉じることでレスポンス本文を終了します。 応答の長さに値-1が含まれている場合、応答本体は送信されません。

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

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

実装上のノート:

この実装によって、コール元は、交換終了後にConnection: closeヘッダーを「レスポンス・ヘッダー」に提供して、sendResponseHeadersの呼出し前に接続を強制的にクローズするようにサーバーに指示できます。

パラメータ:

rCode - 送信する応答コード

responseLength - > 0,がレスポンス本文の固定長を指定し、getResponseCode()から取得したストリームに正確なバイト数を書き込む必要がある場合、== 0,ではチャンク・エンコーディングが使用され、任意のバイト数を書き込むことができます。 <= -1の場合、レスポンス本文の長さは指定されず、レスポンス本文は書き込まれません。

例外:

IOException - レスポンス・ヘッダーがすでに送信されている場合、またはI/Oエラーが発生した場合

関連項目:

• getResponseBody()

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