com.sun.net.httpserver

クラス HttpServer

java.lang.Object

com.sun.net.httpserver.HttpServer

直系の既知のサブクラス:

HttpsServer

public abstract class HttpServer
extends Object

このクラスは、単純な HTTP サーバーを実装します。HttpServer は、IP アドレスとポート番号にバインドされ、このアドレスのクライアントからの着信 TCP 接続を待機します。サブクラス HttpsServer は、HTTPS 要求を処理するサーバーを実装します。

要求を処理するためには、1 つ以上の HttpHandler オブジェクトをサーバーと関連付ける必要があります。これらの各 HttpHandler は、このサーバー上のアプリケーションまたはサービスの位置を表すルート URI パスに登録されます。HttpServer へのハンドラのマッピングは、HttpContext オブジェクトによってカプセル化されます。HttpContext は、createContext(String,HttpHandler) を呼び出すことで作成されます。ハンドラが見つからない要求は、応答 404 で拒否されます。スレッドの管理は、Executor オブジェクトを指定することで、このオブジェクトの外部で実行できます。何も指定しない場合は、デフォルトの実装が使用されます。

HttpContext パスへの要求 URI のマッピング

HTTP 要求の受信時に、要求 URI のパスのプレフィックスにもっとも良く一致するパスを持つコンテキストを検索することで、適切な HttpContext とハンドラを特定します。パスは文字どおりに照合されます。つまり、文字列の比較では大文字と小文字が区別され、エンコードされた形式への変換やこれらの形式からの変換は行われません。たとえば、HttpServer で次の HttpContext が構成されているとします。

Context	コンテキストパス
ctx1	"/"
ctx2	"/apps/"
ctx3	"/apps/foo/"

次の表に、いくつかの要求 URI と、一致する可能性があるコンテキストがあればそれを示します。

要求 URI	一致するコンテキスト
"http://foo.com/apps/foo/bar"	ctx3
"http://foo.com/apps/Foo/bar"	一致なし、大文字と小文字の誤り
"http://foo.com/apps/app1"	ctx2
"http://foo.com/foo"	ctx1

ソケットバックログについての注

アドレスとポート番号にバインドするときは、アプリケーションで整数のバックログパラメータも指定できます。これは、システムが内部的にキューに入れる着信 TCP 接続の最大数を表します。接続は、HttpServer で受け入れられるのを待機する間、キューに入れられます。上限に達すると、それ以上の接続は基本となる TCP 実装によって拒否されるか、場合によっては無視されます。正しいバックログ値の設定は、TCP 層でのリソースの効率的な使用 (高すぎる値を設定しない) と、着信要求の適切なスループットの維持 (低すぎる値を設定しない) との間の妥協点になります。

導入されたバージョン:

1.6

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

コンストラクタ

修飾子	コンストラクタと説明
protected	HttpServer()

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
abstract void	bind(InetSocketAddress addr, int backlog) 現在バインドされていない HttpServer を、指定されたアドレスおよびポート番号にバインドします。
static HttpServer	create() 最初にローカルアドレス/ポートにバインドされていない HttpServer インスタンスを作成します。
static HttpServer	create(InetSocketAddress addr, int backlog) 指定された InetSocketAddress (IP アドレスとポート番号) にバインドする HttpServer インスタンスを作成します。 最大バックログも指定できます。
abstract HttpContext	createContext(String path) 最初にハンドラを指定せずに HttpContext を作成します。
abstract HttpContext	createContext(String path, HttpHandler handler) HttpContext を作成します。
abstract InetSocketAddress	getAddress() このサーバーが待機しているアドレスを返します。
abstract Executor	getExecutor() このサーバーの executor オブジェクトが setExecutor(Executor) で指定された場合は、それを返します。何も指定されていない場合は、null を返します。
abstract void	removeContext(HttpContext context) 指定されたコンテキストをサーバーから削除します。
abstract void	removeContext(String path) 指定されたパスによって識別されるコンテキストをサーバーから削除します。
abstract void	setExecutor(Executor executor) このサーバーの Executor オブジェクトを設定します。
abstract void	start() 新しいバックグラウンドスレッドでこのサーバーを起動します。
abstract void	stop(int delay) 待機中のソケットを閉じ、新しい交換を処理できないようにすることで、このサーバーを停止します。

クラス java.lang.Object から継承されたメソッド

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

コンストラクタの詳細

HttpServer

protected HttpServer()

メソッドの詳細

create

public static HttpServer create()
                         throws IOException

最初にローカルアドレス/ポートにバインドされていない HttpServer インスタンスを作成します。HttpServer は、現在インストールされている HttpServerProvider から取得します。このサーバーは、bind(InetSocketAddress,int) を使用してバインドしてからでないと使用できません。

例外:

IOException

create

public static HttpServer create(InetSocketAddress addr,
                int backlog)
                         throws IOException

指定された InetSocketAddress (IP アドレスとポート番号) にバインドする HttpServer インスタンスを作成します。 最大バックログも指定できます。これは、待機中のソケットでキューに入れることができる着信接続の最大数です。キューに入れられた TCP 接続がこの上限を超える場合は、TCP 実装で拒否されることがあります。HttpServer は、現在インストールされている HttpServerProvider から取得します。

パラメータ:

addr - 待機するアドレス。null の場合は、bind() を呼び出してアドレスを設定する必要がある

backlog - ソケットのバックログ。この値がゼロ以下の場合は、システムデフォルト値が使用される。

例外:

BindException - サーバーが要求されたアドレスをバインドできない場合、またはサーバーがすでにバインドされている場合。

IOException

bind

public abstract void bind(InetSocketAddress addr,
        int backlog)
                   throws IOException

現在バインドされていない HttpServer を、指定されたアドレスおよびポート番号にバインドします。最大バックログも指定できます。これは、待機中のソケットでキューに入れることができる着信接続の最大数です。キューに入れられた TCP 接続がこの上限を超える場合は、TCP 実装で拒否されることがあります。

パラメータ:

addr - 待機するアドレス

backlog - ソケットのバックログ。この値がゼロ以下の場合は、システムデフォルト値が使用される。

例外:

BindException - サーバーが要求されたアドレスをバインドできない場合、またはサーバーがすでにバインドされている場合。

NullPointerException - addr が null の場合

IOException

start

public abstract void start()

新しいバックグラウンドスレッドでこのサーバーを起動します。バックグラウンドスレッドは、呼び出し側の優先順位、スレッドグループ、およびコンテキストクラスローダーを継承します。

setExecutor

public abstract void setExecutor(Executor executor)

このサーバーの Executor オブジェクトを設定します。executor は、start() を呼び出す前に設定する必要があります。すべての HTTP 要求は、executor に指定されたタスクで処理されます。start() の前にこのメソッドを呼び出さない場合、または null の executor で呼び出した場合は、デフォルトの実装が使用されます。デフォルトの実装では、start() メソッドで作成されたスレッドが使用されます。

パラメータ:

executor - 設定する executor。デフォルトの実装の場合は null

例外:

IllegalStateException - このサーバーがすでに起動している場合

getExecutor

public abstract Executor getExecutor()

このサーバーの executor オブジェクトが setExecutor(Executor) で指定された場合は、それを返します。何も指定されていない場合は、null を返します。

戻り値:

このサーバーに設定された executor。設定されていない場合は null。

stop

public abstract void stop(int delay)

待機中のソケットを閉じ、新しい交換を処理できないようにすることで、このサーバーを停止します。次にこのメソッドは、現在のすべての交換ハンドラが完了するまで、あるいは遅延秒数がほぼ経過するまで (いずれか先に発生したほうが優先される) ブロックされます。そのあと、開いているすべての TCP 接続が閉じられ、start() で作成されたバックグラウンドスレッドが終了し、メソッドが復帰します。停止後、HttpServer は再利用できません。

パラメータ:

delay - 交換が終了するまでの最大待機時間 (秒)。

例外:

IllegalArgumentException - 遅延が 0 未満の場合。

createContext

public abstract HttpContext createContext(String path,
                        HttpHandler handler)

HttpContext を作成します。HttpContext は、URI パスからこの HttpServer 上の交換ハンドラへのマッピングを表します。作成後、パスに対してサーバーが受信するすべての要求は、指定されたハンドラオブジェクトを呼び出すことで処理されます。コンテキストはパスによって識別され、これを removeContext(String) メソッドとともに使用して、あとでサーバーから削除できます。

パスはこのコンテキストのルート URI パスを指定します。パスの最初の文字は「/」である必要があります。

このクラスの概要では、着信要求 URI が HttpContext インスタンスにマップされる方法を記述しています。

パラメータ:

path - コンテキストを関連付けるルート URI パス

handler - 着信要求を呼び出すハンドラ。

例外:

IllegalArgumentException - パスが無効な場合、またはこのパスのコンテキストがすでに存在する場合

NullPointerException - パスまたはハンドラのいずれかが null の場合

createContext

public abstract HttpContext createContext(String path)

最初にハンドラを指定せずに HttpContext を作成します。ハンドラは、HttpContext.setHandler(HttpHandler) を使用してあとで指定する必要があります。HttpContext は、URI パスからこの HttpServer 上の交換ハンドラへのマッピングを表します。作成後、ハンドラが設定されると、パスに対してサーバーが受信するすべての要求が、ハンドラオブジェクトを呼び出すことで処理されます。コンテキストはパスによって識別され、これを removeContext(String) メソッドとともに使用して、あとでサーバーから削除できます。

パスはこのコンテキストのルート URI パスを指定します。パスの最初の文字は「/」である必要があります。

このクラスの概要では、着信要求 URI が HttpContext インスタンスにマップされる方法を記述しています。

パラメータ:

path - コンテキストを関連付けるルート URI パス

例外:

IllegalArgumentException - パスが無効な場合、またはこのパスのコンテキストがすでに存在する場合

NullPointerException - パスが null の場合

removeContext

public abstract void removeContext(String path)
                            throws IllegalArgumentException

指定されたパスによって識別されるコンテキストをサーバーから削除します。コンテキストを削除しても、現在処理されている交換には影響を与えませんが、新しい交換は受け入れられなくなります。

パラメータ:

path - 削除されるハンドラのパス

例外:

IllegalArgumentException - このパスに対応するハンドラが存在しない場合。

NullPointerException - パスが null の場合

removeContext

public abstract void removeContext(HttpContext context)

指定されたコンテキストをサーバーから削除します。コンテキストを削除しても、現在処理されている交換には影響を与えませんが、新しい交換は受け入れられなくなります。

パラメータ:

context - 削除するコンテキスト

例外:

NullPointerException - context が null の場合

getAddress

public abstract InetSocketAddress getAddress()

このサーバーが待機しているアドレスを返します。

戻り値:

サーバーが待機しているアドレス/ポート番号