javax.servlet
インタフェース ServletContext

public interface ServletContext

Servlet が Servlet コンテナと通信する際に使用するメソッドをいくつか定義しています。 例えば、ファイルの MIME タイプを取得する、リクエストをディスパッチする、 ログファイルに出力するといったメソッドです。

Java VM 上に "Web アプリケーション"が存在しますが、 コンテキストは各 Web アプリケーションに一つずつ存在します。 ("Web アプリケーション" というのは例えば /catalog のようなサーバの URL 名前空間のサブセットで指定できるパスに置かれた複数の Servlet やコンテンツで構成されています。Web アプリケーションは拡張子が .war となっているファイルでインストールすることも可能です。)

配備記述子で "distributed" と指定された Web アプリケーションの場合はそれぞれの仮想マシンにコンテキストが一つだけあります。 このケースではコンテキストをコンテナ全般に渡る情報を共有する場所として使用できません (これは情報が実際には全体的ではないためです)。 代わりにデータベースのような外部リソースを使ってください。

ServletContext オブジェクトは Web サーバが Servlet を初期化したときに Servlet に提供する ServletConfig オブジェクトに含まれています。

バージョン:

$Version$

作成者:

Various

関連項目:

Servlet.getServletConfig(), ServletConfig.getServletContext()

メソッドの概要

Object	getAttribute(String name) 指定された名前に対応する Servlet コンテナの属性を返します。
Enumeration	getAttributeNames() Servlet コンテキスト内の利用可能な属性名を含む Enumeration オブジェクトを返します。
ServletContext	getContext(String uripath) 指定された URL に対応する ServletContext オブジェクトを返します。
String	getInitParameter(String name) 指定された名前の初期化パラメータの値を含む文字列を返します。
Enumeration	getInitParameterNames() そのコンテキストの初期化パラメータの名前を String 列挙である Enumeration で返します。
int	getMajorVersion() この Servlet コンテナがサポートしている Java Servlet API のメジャーバージョンを返します。
String	getMimeType(String file) 指定されたファイルの MIME タイプを返します。
int	getMinorVersion() この Servlet コンテナがサポートしている Java Servlet API のマイナーバージョンを返します。
RequestDispatcher	getNamedDispatcher(String name) 指定された Servlet のラッパーとして動作する RequestDispatcher オブジェクトを返します。
String	getRealPath(String path) 与えられた仮想パスに対応する実際のパスを String オブジェクトで返します。
RequestDispatcher	getRequestDispatcher(String path) 指定されたパスに位置するリソースのラッパーとして動作する RequestDispatcher オブジェクトを返します。
URL	getResource(String path) 指定されたパスでマッピングされているリソースの URL を返します。
InputStream	getResourceAsStream(String path) 指定されたパスに相当するリソースを InputStream オブジェクトで返します。
Set	getResourcePaths(String path) 引数で指定されたパスに一致するものが Web アプリケーション内にあると、 そのサブパス以下にある全てのリソースのパス名をディレクトリに似た形式のリストにして返します。
String	getServerInfo() Servlet が動作している Servlet コンテナの名前やバージョンを返します。
Servlet	getServlet(String name) 推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。 このメソッドは以前 ServletContext から Servlet を取得するために定義されたものでした。 このバージョンでは、常に null を返します。 単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。 このメソッドを使わなくても Servlet は ServletContext クラスを使って情報の共有ができるようになっています。 また、Servlet ではない、 一般的なクラスのメソッドを起動することで共通のビジネスロジックを実行できます。
String	getServletContextName() この Web アプリケーションの名前を返します。
Enumeration	getServletNames() 推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。 このメソッドは以前、このコンテキストに存在することがわかっている Servlet の名前を全て取得して Enumeration で返すように定義されていました。 このバージョンでは、このメソッドは常に空の Enumeration を返します。単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。
Enumeration	getServlets() 推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。 このメソッドは以前、この Servlet コンテキストに存在することがわかっている全てのServlet を取得して Enumerationオブジェクトを返すように定義されていました。 このバージョンでは、このメソッドは常に空の Enumeration を返します。単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。
void	log(Exception exception, String msg) 推奨されていません。 Java Servlet API 2.1 以降。 代わりに log(String message, Throwable throwable) を使ってください。 このメソッドは以前、例外のスタックトレースとその説明となるエラーメッセージを Servlet のログファイルに出力するために定義されていました。
void	log(String msg) Servlet ログファイルに指定されたメッセージを出力します。
void	log(String message, Throwable throwable) 与えられた Throwable 例外の説明となるメッセージとスタックトレースを Servlet のログファイルに出力します。
void	removeAttribute(String name) Servlet コンテキストから指定された名前の属性を削除します。
void	setAttribute(String name, Object object) この Servlet コンテキスト内で指定された属性名にオブジェクトを結び付けます。

メソッドの詳細

getContext

public ServletContext getContext(String uripath)

指定された URL に対応する ServletContext オブジェクトを返します。

このメソッドを使うとコンテキストにアクセスできるようになります。 コンテキストにはサーバのさまざまな資源がありますが、 RequestDispatcher オブジェクトを取得するのにもコンテキストが必要です。 "/" で始まるパスはサーバのドキュメントルートに対する相対的なパスと解釈されますが、 同一のコンテナで提供されている他の Web アプリケーションのコンテキストルートと一致します。

セキュリティが重視される環境では URL が指定されても Servlet コンテナは null を返すことがあります。

パラメータ:

uripath - 同一コンテナ上の他のWeb アプリケーションのコンテキストパスを指定するString

戻り値:

指定された URL に対応する ServletContext オブジェクト。ただし、存在しない場合や、 そのようなアクセスを制限しようとしているコンテナでは null

関連項目:

RequestDispatcher

getMajorVersion

public int getMajorVersion()

この Servlet コンテナがサポートしている Java Servlet API のメジャーバージョンを返します。Version 2.3 の実装ならば、 このメソッドは整数の 2 を返さなければなりません。

戻り値:

2

getMinorVersion

public int getMinorVersion()

この Servlet コンテナがサポートしている Java Servlet API のマイナーバージョンを返します。Version 2.3 の実装ならば、 このメソッドは整数の 3 を返さなければなりません。 (訳注:原文に誤りがあるので訂正している。)

戻り値:

3

getMimeType

public String getMimeType(String file)

指定されたファイルの MIME タイプを返します。MIME タイプが不明の場合は null を返します。 MIME タイプは Servlet コンテナのコンフィギュレーションから判断されますが、 Web アプリケーションの配備記述子で指定されることもあります。 よく使われる MIME タイプには "text/html" や "image/gif" があります。

パラメータ:

file - ファイル名を指定する String

戻り値:

ファイルの MIMEタイプを意味する String

getResourcePaths

public Set getResourcePaths(String path)

引数で指定されたパスに一致するものが Web アプリケーション内にあると、 そのサブパス以下にある全てのリソースのパス名をディレクトリに似た形式のリストにして返します。 "/" で終るパスはサブディレクトリを意味しています。 戻り値として得られるパス名は Web アプリケーションのルートからの相対パスであり、 "/" で始まります。例えば次のような Web アプリケーションがあったとします。

/welcome.html
/catalog/index.html
/catalog/products.html
/catalog/offers/books.html
/catalog/offers/music.html
/customer/login.jsp
/WEB-INF/web.xml
/WEB-INF/classes/com.acme.OrderServlet.class,

この Web アプリケーションで getResourcePaths("/") を実行すると {"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"} が得られます。
getResourcePaths("/catalog/") を実行すると {"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"} が得られます。

パラメータ:

path - 一致するリソースを探すのに使われるパスの一部。 "/" で始めなければなりません

戻り値:

ディレクトリリストを含む Set。 指定されたパスに相当するリソースがその Web アプリケーションに無い場合は null

導入されたバージョン:

Servlet 2.3

getResource

public URL getResource(String path)
                throws MalformedURLException

指定されたパスでマッピングされているリソースの URL を返します。 指定するパスは "/" で始まっていなければなりません。また、 そのリソースが存在する Web アプリケーションのコンテキストルートからの相対パスであると解釈されます。

このメソッドを使うと、Servlet コンテナはどのような資源でも Servlet からリソースとして利用できるようにします。リソースはローカル・ リモート双方のファイルシステム上、データベース内、.war ファイル内に存在していても利用できます。

Servlet コンテナはリソースにアクセスする際に必要になる URL ハンドラと java.net.URLConnection オブジェクトを実装しなければなりません。

指定されたパス名にマッピングされているリソースが無い場合は null を返します。

コンテナによってはこのメソッドが返す URL に java.net.URL クラスのメソッドを使って出力できるようになっている場合があります。

リソースの内容が直接返されるので、.jsp ページをリクエストすると JSP のソースコードが返されるので注意が必要です。 実行結果をインクルードする場合はこのメソッドではなく RequestDispatcher を使ってください。

このメソッドにはクラスローダに基づくリソース探索を行う java.lang.Class#getResource() メソッドとは違う目的があります。

パラメータ:

path - リソースへのパスを指定する String

戻り値:

指定のパスに存在するリソース。 該当するリソースが無い場合は null

例外:

MalformedURLException - パス名が正しい形式で与えられなかった場合

getResourceAsStream

public InputStream getResourceAsStream(String path)

指定されたパスに相当するリソースを InputStream オブジェクトで返します。

InputStream オブジェクトには、 さまざまなタイプや長さのデータが含まれるます。 指定するパスは getResource で説明した規則にしたがっていなければなりません。 指定されたパスにリソースが無い場合、null を返します。

getResource メソッドでは、Content-Length や Content-Type のようなメタ情報を取得できますが、 このメソッドを使うと取得できなくなります。

Servlet コンテナはリソースアクセス時に必要になる URL ハンドラと java.net.URLConnection オブジェクトを実装しなければなりません。

このメソッドはクラスローダを使う java.lang.Class#getResourceAsStream() メソッドと違います。 このメソッドは Servlet コンテナがクラスローダを使わずに、 どのような場所からでも Servlet がリソースを利用できるようにするものです。

戻り値:

Servlet に返すInputStream オブジェクト。 指定されたパスにリソースが存在しない場合は null

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(String path)

指定されたパスに位置するリソースのラッパーとして動作する RequestDispatcher オブジェクトを返します。 RequestDispatcher オブジェクトはリソースにリクエストをフォワードするか、 レスポンスのなかのリソースをインクルードする目的で使用します。 リソースは動的、静的どちらにも適用できます。

パス名は "/" で始まらなくてはいけません。このようになっていると、 この Web アプリケーションのコンテキストルートに対する相対パスであると解釈されます。 外部のコンテキストに属するリソースを利用するには getContext() メソッドを使って RequestDispatcher オブジェクトを取得してください。この メソッドは ServletContext が RequestDispatcher を返せなかった場合に null を返します。

パラメータ:

path - リソースのパス名を指定する String

戻り値:

指定されたパスに相当するリソースのラッパーとして動作する RequestDispatcher オブジェクト

関連項目:

RequestDispatcher, getContext(java.lang.String)

getNamedDispatcher

public RequestDispatcher getNamedDispatcher(String name)

指定された Servlet のラッパーとして動作する RequestDispatcher オブジェクトを返します。

Servlet(JSP ページも同様)はサーバのアドミニストレーションや Web アプリケーションの配備記述子で名前が与えられることがあります。 Servlet のインスタンスは ServletConfig.getServletName() メソッドを使って名前が解決されることもあります。

このメソッドは ServletContext が何かの問題で RequestDispatcher を返せない場合には null を返します。

パラメータ:

name - Servlet をラップしている名前を指定する String オブジェクト

戻り値:

指定された Servlet のラッパーとして動作する RequestDispatcher オブジェクト

関連項目:

RequestDispatcher, getContext(java.lang.String), ServletConfig.getServletName()

getServlet

public Servlet getServlet(String name)
                   throws ServletException

推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。

このメソッドは以前 ServletContext から Servlet を取得するために定義されたものでした。 このバージョンでは、常に null を返します。 単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。

このメソッドを使わなくても Servlet は ServletContext クラスを使って情報の共有ができるようになっています。 また、Servlet ではない、 一般的なクラスのメソッドを起動することで共通のビジネスロジックを実行できます。

ServletException

getServlets

public Enumeration getServlets()

推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。

このメソッドは以前、この Servlet コンテキストに存在することがわかっている全てのServlet を取得して Enumerationオブジェクトを返すように定義されていました。 このバージョンでは、このメソッドは常に空の Enumeration を返します。単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。

getServletNames

public Enumeration getServletNames()

推奨されていません。 Java Servlet API 2.1 以降。 直接的な代替手段はありません。

このメソッドは以前、このコンテキストに存在することがわかっている Servlet の名前を全て取得して Enumeration で返すように定義されていました。 このバージョンでは、このメソッドは常に空の Enumeration を返します。単に、バイナリ互換を保つ目的で残してあるにすぎません。 Java Servlet API の今後のバージョンでは完全に削除されるでしょう。

log

public void log(String msg)

Servlet ログファイルに指定されたメッセージを出力します。 通常は event ログです。Servlet ログファイルの名前やタイプは Servlet コンテナによって違います。

パラメータ:

msg - ログファイルに出力するメッセージを指定する String

log

public void log(Exception exception,
                String msg)

推奨されていません。 Java Servlet API 2.1 以降。 代わりに log(String message, Throwable throwable) を使ってください。

このメソッドは以前、例外のスタックトレースとその説明となるエラーメッセージを Servlet のログファイルに出力するために定義されていました。

log

public void log(String message,
                Throwable throwable)

与えられた Throwable 例外の説明となるメッセージとスタックトレースを Servlet のログファイルに出力します。 Servlet ログファイルは通常は event ログですが、名前やタイプは Servlet コンテナによって違います。

パラメータ:

message - エラーや例外を解説する String

throwable - Throwable エラーや例外

getRealPath

public String getRealPath(String path)

与えられた仮想パスに対応する実際のパスを String オブジェクトで返します。例えば、"/index.html" というパスが与えられたとするとサーバのファイルシステム上の絶対パスを返します。 そのパスは "http://host/contextPath/index.html" がリクエストされたときに提供するファイルのパスです。 ここで、contextPath というのはこの ServletContext のコンテキストパスを意味しています。

戻り値で得られる実際のパスは Servlet コンテナが動作しているコンピュータやオペレーティングシステムに合わせた形式に変換されます。 パスセパレータも適切な形式になっています。このメソッドは Servlet コンテナが何かの理由(コンテンツが .war アーカイブで提供されているなど) で仮想パスを実際のパスに変換できなかった場合には null を返します。

パラメータ:

path - 仮想パスを指定する String

戻り値:

実際のパスを表す String。 ただし、変換されなかった場合は null

getServerInfo

public String getServerInfo()

Servlet が動作している Servlet コンテナの名前やバージョンを返します。

サーブレット名/バージョン番号という形式の文字列が返されます。 例えば JavaServer Web Development Kit ならば JavaServer Web Dev Kit/1.0 という文字列が返されます。

Servlet コンテナは名前やバージョン以外に付加的な情報を返すこともあります。 そのような情報は最初の文字列のあとに括弧でくくって JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86) のようになっています。

戻り値:

Servlet コンテナの名前とバージョンが必ず含まれている String

getInitParameter

public String getInitParameter(String name)

指定された名前の初期化パラメータの値を含む文字列を返します。 初期化パラメータはコンテキスト内で有効です。 指定されたパラメータが存在しない場合は null を返します。

このメソッドを使うと "Web アプリケーション" 全体で有効な設定情報を利用できるようになります。例えば、 ウェブマスターの email アドレスや重要なデータを維持しているシステムの名前などを提供するのに使えます。

パラメータ:

name - 値が要求されるパラメータの名前を表す String

戻り値:

指定された名前に相当する初期化パラメータの値である String
(訳注: 原文は getServerInfo() をコピーしたまま修正を 忘れていたため、訂正している。)

関連項目:

ServletConfig.getInitParameter(java.lang.String)

getInitParameterNames

public Enumeration getInitParameterNames()

そのコンテキストの初期化パラメータの名前を String 列挙である Enumeration で返します。 コンテキストに初期化パラメータが無い場合は空の Enumeration を返します。

戻り値:

そのコンテキストの初期化パラメータの名前が含まれているString からなる Enumeration

関連項目:

ServletConfig.getInitParameter(java.lang.String)

getAttribute

public Object getAttribute(String name)

指定された名前に対応する Servlet コンテナの属性を返します。 対応する属性が無い場合は null を返します。 属性を利用すると Servlet コンテナは Servlet に付加的な情報を与えることができるようになります。 その情報はこのインタフェースにより提供済みのものばかりではありません。 属性の情報については使っているサーバのドキュメントを参照してください。 サポートされている属性の一覧は getAttributeNames メソッドで取得できます。

属性は java.lang.Object か何かのサブクラスで返されます。 属性名はパッケージ名のネーミングコンベンションに従うべきです。 java.*, javax.*, sun.* に該当する名前は Java Servlet API 仕様で予約されています。

パラメータ:

name - 属性の名前を指定する String

戻り値:

属性値である Object 。 指定された名前に一致する属性が無い場合は null

関連項目:

getAttributeNames()

getAttributeNames

public Enumeration getAttributeNames()

Servlet コンテキスト内の利用可能な属性名を含む Enumeration オブジェクトを返します。 属性値を取得するには属性名を指定して getAttribute(java.lang.String) メソッドを使ってください。

戻り値:

属性名からなる Enumeration

関連項目:

getAttribute(java.lang.String)

setAttribute

public void setAttribute(String name,
                         Object object)

この Servlet コンテキスト内で指定された属性名にオブジェクトを結び付けます。 指定した名前がすでに使われている場合にはこのメソッドは新しい属性で置き換えます。

ServletContext にイベントリスナーが設定されている場合はコンテナは状況に応じてリスナーに通知します。

値として null が渡された場合、removeAttribute() を実行したのと同等の結果になります。

属性名はパッケージ名と同じ命名規約に従うべきです。 java.*, javax.*, sun.* に該当する名前は Java Servlet API 仕様で予約されています。

パラメータ:

name - 属性名を指定する String

object - 属性に結びつける値を意味する Object。

removeAttribute

public void removeAttribute(String name)

Servlet コンテキストから指定された名前の属性を削除します。 削除されると、それ以降にこの名前で getAttribute(java.lang.String) が実行されると null を返します。

ServletContext にイベントリスナーが設定されている場合はコンテナは状況に応じてリスナーに通知します。

パラメータ:

name - 削除する属性の名前を指定する String

getServletContextName

public String getServletContextName()

この Web アプリケーションの名前を返します。名前は配備記述子の display-name 要素で与えられた Web アプリケーション名であり、 この ServletContext を指しています。

戻り値:

Web アプリケーションの名前。 配備記述子で名前が宣言されていない場合は null 。

導入されたバージョン:

Servlet 2.3