Apache Tomcat 6.0

Apache Tomcat 設定リファレンス

Context コンテナ

Context 要素は (特定の仮想ホストで実行される) １個の web アプリケーションを表す。 Servlet Specification (2.2 版以降) に記述されるように，各 web アプリケーションは Web Application Archive (WAR) ファイル，またはそれを展開した内容を含むディレクトリをベースをする。 web application archive についてさらに情報を得るには， Servlet Specification をダウンロードし，Tomcat Application Developer's Guide をレビューするとよい。

それぞれの HTTP リクエストを処理するために使われる web アプリケーションは，定義された各 Context の context path に対するリクエスト URI の最長可能プレフィックス (the longest possible prefix) のマッチングに基づき，Catalina によって選択される。いったん選択されると，次にその Context が， web アプリケーション配備記述子ファイル (これはその web アプリのディレクトリ階層の /WEB-INF/web.xml に位置していなくてはならない) に定義されたサーブレット・マッピングにしたがって，到来するリクエストを処理するのにふさわしいサーブレットを選択する。

君は好きなだけ多くの Context 要素を定義してよい。そのような Context はそれぞれ一意的な context path を持たなくてはならない。さらに，どれか１個の Context は長さゼロの文字列に等しい context path で存在しなくてはならない。この Context が，この仮想ホストのデフォルトの web アプリケーションになり，他のどの Context の context path にもマッチしないすべてのリクエストを処理するために使われる。

Tomcat 6 では，Tomcat 4.x と異なり， <Context> 要素を直接 server.xml ファイルに置くことは推奨されない。 なぜなら，Tomcat を再起動することなしにはメインの conf/server.xml ファイルを再ロードできないから，Context 設定の修正がより出しゃばったものになるからである。

Context は下記の場所に陽に定義できる:

$CATALINA_HOME/conf/context.xml ファイルに: Context 要素の情報はすべての web アプリによってロードされる。

$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml.default ファイルに: Context 要素の情報はその host のすべての web アプリによってロードされる。

$CATALINA_HOME/conf/[enginename]/[hostname]/ ディレクトリの個々のファイル (拡張子は ".xml") に。ファイルの名前 (.xml 拡張子を除く) が context path として使われる。マルチ=レベルの context path は # を使って，例えば context#path.xml のように定義できる。デフォルトの web アプリケーションは ROOT.xml という名前のファイルを使って定義できる。

もしも上述のファイルがこのアプリケーションに対して見つからないときは，アプリケーション・ファイルの中の /META-INF/context.xml にある個別ファイルに。

メインの conf/server.xml の中の Host 要素内部に。

陽に指定される Context 要素に加えて，君のために Context 要素が自動的に生成されるようにするテクニックがいくつかある。詳しくは Automatic Application Deployment と User Web Applications を見よ。

以下の記述では，君が Tomcat 5 [ママ] をインストールしたディレクトリを参照するために変数名 $CATALINA_HOME を使う。これは大多数の相対パスの解決に使われるベースディレクトリである。しかし，もしも君が CATALINA_BASE ディレクトリをセットすることによって，複数インスタンス用に Tomcat 5 を設定しているならば， $CATALINA_HOME のそれぞれの参照に対し，かわりに $CATALINA_BASE を使うべきである。

属性

共通属性

Context のすべての実装は次の属性をサポートする。

Attribute Description
backgroundProcessorDelay
この値は，この context およびその子コンテナ (すべての wrapper を含む) での backgroundProcess メソッドの呼出しと呼出しの間の遅延 (秒) を表す。子コンテナの遅延値が非負ならば (子コンテナが自分自身の処理スレッドを使うことを意味するから)， [context の処理スレッドがわざわざ] 子コンテナ [のメソッド] を呼び出すことはしない。この値を正にすると [その context 用の処理] スレッドが１本，生成される。指定された秒数だけ待ってから，このスレッドはこの host [←おそらく context の誤り] およびその子コンテナすべての backgroundProcess メソッドを [どれか１個] 呼び出す。 context は background 処理を使ってセッションの有効期限切らしと再ロードのためのクラス看視を実行する。指定しなければ，属性のデフォルト値は -1 である。これは context が自分の親である host の background 処理スレッドに頼ることを意味する。

className
使用する実装の Java クラス名。このクラスは org.apache.catalina.Context インタフェースを実装しなければならない。指定しなければ，標準実装 (下記で定義) が使われる。

cookies
クライアントによってサポートされているとき，セッション識別子の通信のためにクッキーを使いたいならば，これを true にセットせよ (これがデフォルトである)。セッション識別子の通信のためにクッキーを使うことを禁止し，アプリケーションによる URL 書き換えだけに頼りたいならば，これを false にセットせよ。

crossContext
このアプリケーション内での ServletContext.getContext() の呼出しが，この仮想ホストで走っている他の web アプリケーションへのリクエストディスパッチャを成功裏に返すようにしたいならば，これを true にセットせよ。セキュリティを意識した環境で， getContext() が常に null を返すようにしたいならば，これを false にセットせよ (これがデフォルトである)。

docBase
この web アプリケーションのための Document Base (別名 Context Root ) ディレクトリ，または (もしもこの web アプリケーションが WAR ファイルから直接実行されているならば) WAR ファイルへのパス名。君はこのディレクトリまたは WAR ファイルへの絶対パス名を指定してもよいし，自分の Host の appBase ディレクトリからの相対パス名を指定してもよい。

override
この Context 要素での陽な設定が，自分の Host の DefaultContext 要素での対応する設定を上書きできるようにしたいならば，これを true にセットせよ。デフォルトでは，DefaultContext 要素での設定が使われる。

もしもシンボリックリンクが docBase に使われているならば，シンボリックリンクへの変更は Tomcat の再起動または context の配備解除と再配備の後にだけ効果をもつ。 context の再ロード [だけで] は十分ではない。

privileged
この context が manager サーブレットのようなコンテナサーブレットを使えるようにするには，これを true にセットせよ。
[コンテナサーブレットの原語は container serlvet です。サーブレットのコンテナ (つまり Tomcat) を制御できる特権をもったサーブレット，という意味でしょうか？]

path
この web アプリケーションの context path。処理にふさわしい web アプリケーションを選択するために，各リクエスト URL の先頭とマッチされる。１個の Host 内のすべての context path は一意的でなければならない。空の文字列 ("") の context path を指定すると，その Host のための，他の Context に割り当てられていないすべてのリクエストを処理するデフォルト の web アプリケーションを定義することになる。 server.xml で静的に Context を定義する場合を除き，このフィールドの値を設定してはならない。 .xml context ファイルや docBase に使われるファイル名から推論されるからである。

reloadable
Catalina に /WEB-INF/classes/ と /WEB-INF/lib にあるクラスが変更されていないかどうかを看視させ，変更の検出時に自動的にその web アプリケーションを再ロードさせたいならば，これを true にセットせよ。この機能はアプリケーション開発時には非常に有用だが，顕著な実行時オーバヘッドを要するから，製品アプリケーションを配備して使用するときには勧められない。これが，この属性のデフォルト設定が false である理由である。だが君は，配備されたアプリケーションの再ロードを必要に応じて引き起こすために， Manager web アプリケーションを使うことができる。

wrapperClass
この Context の管理下にあるサーブレットのために使われる org.apache.catalina.Wrapper 実装クラスの Java クラス名。指定しなければ，標準のデフォルト値が使われる。

標準実装

Context の標準実装は org.apache.catalina.core.StandardContext である。 (上記の共通属性に加えて) 次の付加的な属性をサポートする:

Attribute Description
allowLinking
もしもこのフラグの値が true ならば， web アプリケーション内でシンボリックリンクが許され， web アプリケーションの base path の外側のリソースを参照できる。指定しなければ，フラグのデフォルト値は false である。

注意: Windows プラットフォームで (または英字の大小を区別するファイルシステムを持たないほかのどんな OS でも) このフラグを true にセットしてはならない。セキュリティ問題，とりわけ case sensitivity check を無効にして JSP ソースコードの暴露を許すことになる問題がある。
[Tomcat にとって同一の場所にあるファイルと判断できれば，例えば a.jsp のかわりに a.JsP が参照されてもチェックできます。しかし，シンボリックリンク経由でそのチェックができなければ， a.JsP という名前による非 JSP 的なアクセスを許してしまいます。]

antiJARLocking
もしも ture ならば，Tomcat のクラスローダは，リソースを JAR 内部から URL 経由でアクセスするとき， JAR ファイルロッキングを回避するように特別な手段をとる。これはアプリケーションの起動時間に [悪] 影響を与えると予想されるが，ファイルロッキングが起こり得るプラットフォームや設定状況によっては有用であると立証され得る。指定しなければ，デフォルト値は false である。

antiResourceLocking
もしも true ならば，Tomcat はいかなるファイルロッキングも防ごうとする。これはアプリケーションの起動時間に顕著な [悪] 影響を与えると予想されるが，ファイルロッキングが起こり得るプラットフォームや設定状況での web アプリの完全なホットデプロイやデプロイ解除を可能にする。指定しなければ，デフォルト値は false である。

これを true にセットすると，実行中のサーバで JSP の再ロードが不可能になることを含め，若干の副作用があることに注意されたい。 Bugzilla 37668 を見よ。

Host の appBase (デフォルトでは webapps ディレクトリ) の外側にあるアプリケーションでこのフラグを true にすると，そのアプリケーションが Tomcat のシャットダウン時に削除されることに注意されたい。君はおそらくそうなって欲しくないはずだから，Host の appBase の外側にある web アプリで antiResourceLocking=true にセットするときは，その前に２度は考えよ。

cacheMaxSize
キロバイト単位での静的リソースキャッシュの最大サイズ。指定しなければ，デフォルト値は 10240 (10 メガバイト) である。

cacheTTL
キャッシュエントリの再バリデーション (revalidation) 間のミリ秒単位での時間。指定しなければ，デフォルト値は 5000 (5 秒) である。

cachingAllowed
もしもこのフラグの値が true ならば，静的リソースに対してキャッシュが使われる。指定しなければ，フラグのデフォルト値は true である。

caseSensitive
もしもこのフラグの値が true ならば，すべての case sensitivity check が無効にされる。指定しなければ，フラグのデフォルト値は true である。

注意: Windows プラットフォームで (または英字の大小を区別するファイルシステムを持たないほかのどんな OS でも) このフラグを false にセットしてはならない。セキュリティ問題，とりわけ case sensitivity check を無効にして JSP ソースコードの暴露を許すことになる問題がある。

processTlds
context が起動時に TLD [Tag Library Descriptor] を処理すべきかどうか。デフォルトは true である。 false の設定は，TLD が web アプリの一部でないと前もって分かっている特別な場合のためにある。

swallowOutput
もしもこのフラグが true ならば， web アプリケーションによる System.out と System.err へのバイト出力が web アプリケーションの logger へリダイレクトされる。指定しなければ，フラグのデフォルト値は false である。

tldNamespaceAware
もしもこのフラグが true ならば， TLD ファイルの XML バリデーションが名前空間対応 (namespace-aware) になる。もしも君がこのフラグをオンにするときは，おそらく tldValidation もオンにすべきだろう。このフラグのデフォルト値は false であり，true にすることには性能上のペナルティがある。

tldValidation
もしもこのフラグの値が true ならば，TLD ファイルが起動時に XML バリデーションを受ける。このフラグのデフォルト値は false であり，true にすることには性能上のペナルティがある。

unloadDelay
サーブレットがアンロードされるまでコンテナが待つ時間 (ミリ秒単位)。指定しなければ，フラグのデフォルト値は 2000 ミリ秒である。

unpackWAR
もしも true ならば，Tomcat は圧縮された web アプリケーションを走らせる前にそれをすべて展開する。指定しなければ，デフォルト値は true である。

useNaming
これを true (デフォルト値) にセットすると，Catalina がこの web アプリケーションのために JNDI InitialContext を有効にする。これは Java2 Enterprise Edition (J2EE) プラットフォームの規約と互換性がある。

workDir
関連する web アプリケーション内のサーブレットが一時的な読み書きに使うために， Context が用意するスクラッチディレクトリ (scratch directory) へのパス名。このディレクトリは，Servlet Specification に記述されるように javax.servlet.context.tempdir という名前の (java.io.File 型の) サーブレット context 属性によって web アプリケーション内のサーブレットから可視になる。指定しなければ，$CATALINA_HOME/work 直下の適切なディレクトリが用意される。

入れ子コンポーネント

君は下記のユーティリティ・コンポーネントのたかだか１個のインスタンスを，対応する要素を Context 要素のなかに入れ子にすることによって，入れ子にできる:

Loader - この web アプリケーションのためのサーブレットと bean のクラスをロードするために使われる web アプリケーション・クラス・ローダを設定する。通常は，デフォルト設定のクラス・ローダで十分である。

Manager - この web アプリケーションのための HTTP セッションを生成・破棄・永続化するために使われるセッション・マネージャを設定する。通常は，デフォルト設定のセッション・マネージャで十分である。

Realm - レルム (realm) のユーザのデータベースと，ユーザにひもづけられた役割 (role) が，この web アプリケーションのためだけに利用されるように，レルムを設定する。指定しない場合，この web アプリケーションを所有している Host または Engine にひもづけられたレルムを利用する。

Resources - この web アプリケーションにひもづけられた静的リソースへのアクセスに使われるリソース・マネージャを設定する。通常は，デフォルト設定のリソース・マネージャで十分である。

WatchedResource - auto deployer は web アプリケーションの指定された静的リソースが更新されるのを監視し，更新されたときは web アプリケーションを再ロードする。この要素の内容は文字列でなければならない。

特記事項

Logging

context は org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path] ログカテゴリに関連付けられる。ブラケットは実際に名前の一部だから，省略しないように注意せよ。
Access Logs
君が web サーバを走らせるとき，普通生成される出力ファイルの一つがアクセスログである。これは，ある標準的なフォーマットで，サーバが処理した各リクエストについての１行の情報を生成する。 Catalina はオプションとして，web サーバが作成するのと同じ標準的なフォーマット，または任意の数のカスタムフォーマットで，アクセスログを作成する Valve 実装を含んでいる。

君は Engine，Host，または Context によって処理されるすべてのリクエストについてのアクセスログを作成するように Catalina に頼むことができる。このように Valve 要素を入れ子にすればよい:
<Context path="/examples" ...>
  ...
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         prefix="localhost_access_log." suffix=".txt"
         pattern="common"/>
  ...
</Context>
サポートされる設定属性についての詳しい情報については Access Log Valve を見よ。
Automatic Context Configuration

もしも君が標準的な Context 実装を使っているならば， Catalina がスタートしたとき，または，いつであれこの web アプリケーションが再ロードしたとき，次の段取りで設定が自動的に行われる。この機能を有効にするために，なんら特別な設定は不要である。

もしも君が独自の Loader 要素を宣言していないならば，標準の web アプリケーション・クラス・ローダが設定される。

もしも君が独自の Manager 要素を宣言していないならば，標準のセッション・マネージャが設定される。

もしも君が独自の Resources 要素を宣言していないならば，標準のリソース・マネージャが設定される。

conf/web.xml にリストされた web アプリケーション・プロパティが，この web アプリケーションのデフォルト値として処理される。これはデフォルト mapping (例えば，*.jps 拡張子から対応する JSP サーブレットへの mapping) およびその他すべての web アプリケーションに適用される標準的な属性を確立する。

この web アプリケーションの /WEB-INF/web.xml リソースにリストされた web アプリケーション・プロパティが (もしもこのリソースが存在するならば) 処理される。

もしも君の web アプリケーションが，ユーザ認証を必要とし得るセキュリティ制約を指定しているならば，君が選んだ login メソッドを実装する適切な Authenticator が設定される。
Context Parameters
君は，この要素の内側に <Parameter> 要素を入れ子にすることによって，サーブレットの context 初期化パラメタとして web アプリケーションから見える名前付きの値を設定できる。例えば，君はこのように初期化パラメタを作成できる:
<Context ...>
  ...
  <Parameter name="companyName" value="My Company, Incorporated"
         override="false"/>
  ...
</Context>
これは web アプリケーション配備記述子 (/WEB-INF/web.xml) に次の要素を含めることと等価である:
<context-param>
  <param-name>companyName</param-name>
  <param-value>My Company, Incorporated</param-value>
</context-param>
しかし，[<Parameter> 要素を使う方法ならば] この値をカスタマイズするために配備記述子を修正する必要はない。

<Parameter> 要素に対して妥当な属性は次のとおりである。

Attribute Description
description
省略可能な，この context 初期化パラメタの人間可読な説明。

name
作成される context 初期化パラメタの名前

override
もしも君が，web アプリケーション配備記述子にあるのと同じパラメタ名について， <context-param> がここで指定した値より優先されないようにしたいならば，これを false にセットせよ。デフォルトでは優先される。

value
ServletContext.getInitParameter() の呼出しで要求されたとき，アプリケーションへ提示されるパラメタ値
Environment Entries
君は，この要素の内側に <Environment> 要素を入れ子にすることによって，環境エントリのリソースとして web アプリケーションから見える名前付きの値を設定できる。例えば，君はこのように環境エントリを作成できる:
<Context ...>
  ...
  <Environment name="maxExemptions" value="10"
         type="java.lang.Integer" override="false"/>
  ...
</Context>
これは web アプリケーション配備記述子 (/WEB-INF/web.xml) に次の要素を含めることと等価である:
<env-entry>
  <env-entry-name>maxExemptions</param-name>
  <env-entry-value>10</env-entry-value>
  <env-entry-type>java.lang.Integer</env-entry-type>
</env-entry>
しかし，[<Environment> 要素を使う方法ならば] この値をカスタマイズするために配備記述子を修正する必要はない。

<Environment> 要素に対して妥当な属性は次のとおりである。

Attribute Description
description
省略可能な，この環境エントリの人間可読な説明。

name
作成される環境エントリの，java:comp/env context からの相対的な名前。

override
もしも君が，web アプリケーション配備記述子にあるのと同じ環境エントリ名について， <env-entry> がここで指定した値より優先されないようにしたいならば，これを false にセットせよ。デフォルトでは優先される。

type
この環境エントリに対して web アプリケーションが期待する Java クラスの完全限定名。 web アプリケーション配備記述子の <env-entry-type> として妥当な値の一つでなければならない。つまり， java.lang.Boolean, java.lang.Byte, java.lang.Character, java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short, または java.lang.String。

value
JNDI context から要求されたとき，アプリケーションへ提示されるパラメタ値。この値は type 属性によって定義される Java 型へ変換可能でなければならない。
Lifecycle Listeners
もしも君がこの Context がいつ開始または停止したのかを知る必要がある Java オブジェクトを実装したならば，君はそれをこの要素の内側に Listener 要素を入れ子にすることによって宣言できる。君が指定するクラス名は org.apache.catalina.LifecycleListener インタフェースを実装していなければならない。そしてそれ [の暗黙に作られるインスタンス] は，対応するライフサイクルのイベントが発生したとき知らせを受ける [つまり，LifecycleListener#lifecycleEvent(LifecycleEvent) が呼び出される]。
<Context path="/examples" ...>
  ...
  <Listener className="com.mycompany.mypackage.MyListener" ... >
  ...
</Context>
Listener は，この要素から設定可能な任意の個数の付加的なプロパティを持てることに注意せよ。属性名は，標準的なプロパティ・メソッド命名パターンを使って，対応する JavaBean プロパティ名とマッチされる。
Request Filters
君は，取り囲む Engine, Host, または Context の要素へ向けられたそれぞれの到来リクエストについて， IP アドレスやホスト名をチェックするように Catalina に頼むことができる。リモートのアドレスや名前が "accept" および/または "deny" のフィルタに設定されたリストに対してチェックされる。そのリストは Jakarta Regexp 正規表現ライブラリによってサポートされた正規表現構文を使って定義される。 accept できない場所から来たリクエストは HTTP "Forbidden" エラーで拒絶される。フィルタ宣言の例を示す:
<Context path="/examples" ...>
  ...
  <Valve className="org.apache.catalina.valves.RemoteHostValve"
         allow="*.mycompany.com,www.yourcompany.com"/>
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         deny="192.168.1.*"/>
  ...
</Context>
サポートされている設定オプションに関する詳しい情報については， Remote Address Filter と Remote Host Filter を見よ。
Resource Definitions
君は，web アプリケーション配備記述子の <resource-ref> 要素と <resource-env-ref> 要素の JNDI lookup に対して返されるべきリソースの特性を宣言できる。君はこのとき同時に， (もしまだ Tomcat に知られていなければ) 使用すべきオブジェクト・ファクトリと，そのオブジェクト・ファクトリの設定に使われるプロパティを設定するために，必要とされるリソース・パラメタを Resource 要素の属性として定義しなければならない。

例えば，君はこのようにリソース定義を作成できる:
<Context ...>
  ...
  <Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/>
  ...
</Context>
これは web アプリケーション配備記述子 (/WEB-INF/web.xml) に次の要素を含めることと等価である:
<resource-ref>
  <description>Employees Database for HR Applications</description>
  <res-ref-name>jdbc/EmployeeDB</res-ref-name>
  <res-ref-type>javax.sql.DataSource</res-ref-type>
  <res-auth>Container</res-auth>
</resource-ref>
しかし，[<Resource> 要素を使えば，わざわざ] この値をカスタマイズするために配備記述子を修正する必要はない [から，例えば war ファイルをそのまま加工せずに利用できる]。

<Resource> 要素に対して妥当な属性は次のとおりである。

Attribute Description
auth
web Applicatoin のコードが対応するリソース・マネージャにプログラム的にサイン・オンするのか，それとも Container がアプリケーションのかわりにリソース・マネージャにサイン・オンするのかを指定する。この属性の値は Applicatoin または Container でなければならない。 web アプリケーションが web アプリケーション配備記述子で <resource-ref> 要素を使うときは，この属性は必須だが，同アプリケーションが <resource-env-ref> 要素を使うときは，省略可能である。

description
省略可能な，このリソースの人間可読な説明。

name
作成されるリソースの，java:comp/env context からの相対的な名前。

scope
このリソース・マネージャを経由して得られた接続が共有可能かどうかを指定する。この属性の値は Shareable または Unshareable でなければならない。デフォルトでは，接続は共有可能 (Shareable) と仮定される。

type
web アプリケーションがこのリソースに対して lookup したときに期待する Java クラスの完全限定名。
Resource Links
この要素はグローバルな JNDI リソースへのリンクを生成するために使われる。そのリンク名での JNDI lookup は，リンクされたグローバル・リソースを返すことになる。

例えば，君はこのようにリソース・リンクを生成できる。
<Context ...>
  ...
  <ResourceLink name="linkToGlobalResource"
            global="simpleValue"
            type="java.lang.Integer"
  ...
</Context>
<ResourceLink> 要素に対して妥当な属性は次のとおりである:

Attribute Description
global
リンクされるグローバル・リソースの (グローバルな JNDI コンテキストでの) 名前。

name
生成されるリソース・リンクの (java:comp/env コンテキストへの相対的な) 名前。

type
web アプリケーションがこのリソース・リンクを lookup したとき， web アプリケーションが期待する完全修飾の Java クラス名
Transaction

君は java:comp/UserTransaction の JNDI lookup に対して返される UserTransaction の性質を宣言できる。君は，このオブジェクトをインスタンス化するためのオブジェクト・ファクトリ・クラスおよび必要とされるリソース・パラメタを， Transaction の属性およびそのオブジェクト・ファクトリを設定するために使われるプロパティとして定義しなければ ならない。

<Transaction> 要素に対して妥当な属性は次のとおりである:

Attribute Description
factory
JNDI オブジェクト・ファクトリのクラス名