1. Top
  2. Tomcat
  3. web.xml

webアプリケーションの設定(web.xml)


Webアプリケーション単位の設定は、各WebアプリケーションのWEB-INFディレクトリにあるweb.xmlで行うことができます。

以下は、Tomcatのweb.xmlの構文を説明します。
ルートとなる要素は常にweb-appとなります。
次の属性を持ちます。
version

このアプリケーションがサポートするweb.xmlのバージョンを指定します。

web-appの子要素になる要素を以下に記述します。



ページの先頭へ

icon

アプリケーションに対応するアイコンを定義します。
これは各種GUIツールで利用されるらしいですが、Tomcatには標準でそういったツールは付いてない(と思う)ので未確認です。
2つの子要素を持ちます。

small-icon

小さいアイコン(16x16)を格納したパスを記述します。

large-icon

大きいアイコン(32x32)を格納したパスを記述します。



ページの先頭へ

display-name

アプリケーションの名前を記述します。
管理マネージャの表示名等に利用されます。




ページの先頭へ

description

アプリケーションの説明文を記述します。
上で紹介した display-name と似ていますが、前者がアプリ簡易名を表すのに対して
こちらではより詳しい記述をするのが適切なのでしょう。



ページの先頭へ

distributable

このアプリケーションが使用するセッションオブジェクトが
全て直列化可能なことを示すときにtrueにします。
デフォルトは false です。
true のとき、直列化不可能(Serializable)なオブジェクトを
セッションに格納しようとすると IllegalArgumentException が発生します。

クラスタリング機能を有効にするとき、この値を true にする必要があります。
参考:distributable



ページの先頭へ

context-param

アプリケーションの初期化パラメータを記述します。
この要素は複数配置することが可能です。
3つの子要素を持ちます。

param-name

パラメータ名を記述します。

param-value

パラメータ値を記述します。

description

パラメータの説明文を記述します(省略可能)。



ページの先頭へ

filter

フィルター定義を記述します。J2EE 1.3で利用可能な要素です。
この要素は複数配置することが可能です。
以下の子要素を持ちます。

icon

フィルターに対応するアイコンを記述します。

filter-name

フィルター名を記述します。

display-name

フィルターの簡易名を記述します。

description

フィルターの説明文を記述します。

filter-class

フィルターに対応するクラス名を完全限定名で記述します。
javax.servlet.Filter インターフェイスを実装している必要があります。

init-param

フィルターの初期化パラメータを記述します。
この要素は複数配置することが可能です。
詳細はcontext-paramを参照して下さい。



ページの先頭へ

filter-mapping

URLとフィルターの対応(マッピング)方法を記述します。
この要素は複数配置することが可能です。
以下の子要素を持ちます。

filter-name

フィルター名を記述します。

url-pattern

フィルターに対応付けられるURLを記述します。
ワイルドカード(*)が使用できます。

servlet-name

フィルターに対応付けられるサーブレットクラス名を記述します。
url-patternとこの要素は同時に記述できません。

dispatcher

フィルターを適用する場面を限定します。
次のいずれかの値を取ります。この要素は複数配置することが可能です。

  • FORWARD

    RequestDispatcher.forward() のコールにより呼び出された時が対象となります。

  • INCLUDE

    RequestDispatcher.include() のコールにより呼び出された時が対象となります。

  • REQUEST

    通常のリクエストコールにより呼び出された時が対象となります。

  • ERROR

    エラーページを表示するために呼び出された時が対象となります。



ページの先頭へ

listener

Listener定義を記述します。
この要素は複数配置することが可能です。

listener-class

Listenerクラス名を完全限定名で記述します。



ページの先頭へ

servlet

サーブレット定義を記述します。
この要素は複数配置することが可能です。
以下の子要素を持ちます。

icon

サーブレットに対応するアイコンを記述します。

servlet-name

サーブレット名を記述します。

display-name

サーブレットの簡易名を記述します。

description

サーブレットの説明文を記述します。

servlet-class

サーブレットに対応するクラス名を完全限定名で記述します。
javax.servlet.http.HttpServlet クラスを継承している必要があります。

jsp-file

サーブレットに対応するJSPファイル名をルートからの相対パスで記述します。
この要素とservlet-class要素は、どちらか一つしか記述できません。

init-param

サーブレットの初期化パラメータを記述します。
この要素は複数配置することが可能です。
詳細はcontext-paramを参照して下さい。

load-on-startup

一つのアプリケーション中に複数の servlet 要素がある場合、
それらを初期化する順序を指定します。値は、0または正の整数である必要があります。
省略した場合、このサーブレットが初期化されるタイミングは
クライアントから最初にサーブレットが呼ばれたときになります。

run-as

このサーブレットを実行するロールを指定します。

description

この要素の説明文を記述します。

role-name

このサーブレットを実行するロール名を指定します。

security-role-ref

この要素は複数配置することが可能です。
詳細は不明です。



ページの先頭へ

JspServlet

デフォルトでJSPファイルを処理するサーブレットが JspServlet です。
$TOMCAT_HOME/conf/web.xml のservlet要素(サーブレット名:jsp)内にこれらの記述があります。
いくつかの初期化パラメータを与えることが出来るので、それを紹介します。

development

Webアプリケーションを「開発モード」で利用するかどうかを指定します。
これを true にすると、JSPファイルを表示する度にそのファイルが更新されたかどうかを調べ、
更新されていればJSPの再コンパイルを行います。
デフォルトは true ですが、運用時にはパフォーマンスを上げる為に false にしておく方が良いでしょう。

reloading

前項の development と似ていますが、こちらは
JSPファイルの更新チェックの頻度を「一定時間毎」とします。
毎回アクセスされる度にチェックをする開発モードよりはパフォーマンス低下も少なく
「アクセスされなくても」自動的に更新チェックを行ってくれる所など開発モードより便利な点もあります。
次項の checkInterval によってチェックする更新頻度を指定します。

デフォルトは true です。
ただし、development が true の場合はこの項目(と次項の checkInterval )は無視されます。

注意する点が2点ほど。
この機能は一定時間毎にJSPファイルが更新されたかどうかをチェックしますが、
その対象となるのは「サーバを起動してから1回でもアクセスのあったファイル」に限ります。
つまり、サーバを起動した直後の状態では自動的にjavaファイルが生成される事はありません。

もう1点は、大量のJSPファイルがあるアプリケーションに対して使用する場合です。
先程説明したように、この機能は「サーバを起動してから1回でもアクセスのあったファイル」を全てチェックします。
これは逆に言えば、一定時間毎に「アクセスのあった全てのファイルをチェックする」事になり
下手をすると開発モード以上の負荷が掛かる可能性があります。

利用するWebアプリケーションの性質やクライアントの利用状況等を考えて
development を使用するか reloading を使用するか、検討してみて下さい。

checkInterval

JSPを再コンパイルするかどうかチェックする間隔を秒単位で指定します。
development が false かつ reloading が true の場合に限り有効です。
デフォルトは300秒です。

compiler

JSPをコンパイルするコンパイラを指定します。
デフォルトではjavacですが、もしjikesを利用したければここに記述する事が出来ます。
コンパイラがパスに通っていなければフルパスで記述する必要があります。

classdebuginfo

JSP(正確にはそれから生成されたjavaファイル)をコンパイルするとき、
生成するクラスファイルにデバッグ情報を含めるかどうかを指定します。
デフォルトではtrueです。

classpath

JSPコンパイル時に使用するクラスパスを指定します。
通常これはTomcatが自動的に設定してくれるので、この項目は
アプリケーションのJSPコンパイルに独自のライブラリが必要が場合等にのみ使用します。

compilerSourceVM

生成するJavaファイルのJDK互換性を指定します。
デフォルトは 1.4 です。

compilerTargetVM

生成するclassファイルのJDK互換性を指定します。
デフォルトは 1.4 です。

enablePooling

タグハンドラのプーリング機能を有効にするかどうかを指定します。
詳細は不明ですが、おそらくタグライブラリ利用時に何らかのデータをメモリ内にプールしておくのだと思います。
デフォルトは true です。

ieClassId

<jsp:plugin>タグ使用時に Internet Explorer に送信する class-id を指定します。
デフォルトは clsid:8AD9C840-044E-11D1-B3E9-00805F499D93 です。

fork

true にすると、Tomcatは自らが起動しているプロセスとは別のプロセスを新たに生成して
そのプロセス内でJSPをコンパイルするようになります。
デフォルトは true です。

javaEncoding

JSPをコンパイルして生成されるjavaファイル(workディレクトリに格納される)の
文字エンコーディングを指定します。
デフォルトは UTF8 です。

genStrAsCharArray

詳細は不明です。

keepgenerated

生成されたjavaファイルを消さずに保持するかどうかを指定します。
デフォルトは true です。
false にした場合、javaファイルは一時的に生成されますがすぐに削除されてclassファイルのみがworkに残ります。

mappedFile

true にすると、JSP内の1行をjavaファイル内の1文に対応させるようにします。
false の場合だと、効率を上げる為にjsp内の複数行が1つの文で表示される事があります。
デフォルトでは false です。デバッグ等でこの処理が必要ならば true にしましょう。

modificationTestInterval

JSPファイルの更新チェック間隔を秒数単位で指定します。
デフォルトは 4 です。
0 にすると、JSPファイルにアクセスする度に更新チェックを行います。

scratchdir

JSPから生成するjavaやclassファイルの格納場所を指定します。
デフォルトでは、格納場所はserver.xmlファイルのworkDir属性に従います。

trimSpaces

ファイル(おそらくJSPファイル)内のスペースをトリムします。
デフォルトは false です。



ページの先頭へ

servlet-mapping

URLとサーブレットの対応(マッピング)方法を記述します。
この要素は複数配置することが可能です。
以下の子要素を持ちます。

servlet-name

サーブレット名を記述します。

url-pattern

サーブレットに対応付けられるURLを記述します。
ワイルドカード(*)が使用できます。

これは、「どのURLにアクセスした場合にどのサーブレットを呼び出すか」という記述をまとめたものです。

例 : デフォルトの$TOMCAT_HOME/conf/web.xmlより抜粋

<servlet>
  <servlet-name>jsp</servlet-name>
  <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
  ...
</servlet>
...
<servlet-mapping>
  <servlet-name>jsp</servlet-name>
  <url-pattern>*.jsp</url-pattern>
</servlet-mapping>

servlet-mappingの各要素を見ると、
???.jsp というURLにアクセスした場合に
jsp という名前のサーブレットを呼び出す事になります。

続いてservlet要素の記述を見ると、これが JspServlet に結び付けられていることが解ります。
以上より、拡張子がjspのファイルは全て JspServlet クラスが処理する事になります。



ページの先頭へ

session-config

セッション関連の記述をします。
1つの子要素を持ちます。

session-timeout

セッションが生成されてから切断されるまでの時間を分単位で指定します。



ページの先頭へ

mime-mapping

ファイル拡張子とMimeタイプの関連付けを行います。
この要素は複数配置することが可能です。
2つの子要素を持ちます。

extension

拡張子(ピリオドは除く)を記述します。

mime-type

拡張子に対応するMimeタイプを記述します。



ページの先頭へ

welcome-file-list

デフォルトファイル名を記述します。
デフォルトファイルとは、URLがスラッシュ(/)で終わっていた場合に表示させるファイルのことです。
対象のディレクトリにデフォルトファイルが存在しない場合、
ディレクトリ一覧画面が表示されてしまうので注意しましょう。

1つの子要素(複数配置可)を持ちます。

welcome-file

デフォルトファイル名を記述します。



ページの先頭へ

error-page

エラー画面に関する情報を記述します。
この要素は複数配置することが可能です。
次の子要素を持ちます。

error-code

HTTPエラーが発生した場合のエラー画面を指定する際には、この要素を利用します。
exception-typeと並列して記述することは出来ません。
HTTPのエラーコード(404など)を記述します。

exception-type

Javaの例外(Exception)が発生した場合のエラー画面を指定する際には、この要素を利用します。
error-codeと並列して記述することは出来ません。
Exceptionのサブクラスを完全限定名で記述します。

location

上で記述したHTTPエラーもしくはJava例外が発生したときに
表示させるエラー画面のURLを記述します。



ページの先頭へ

jsp-config

このアプリケーションで使用するJSPにデフォルトで設定する項目群を定義します。
これを利用することで、今まで全てのJSPファイルに記述する必要があった
文字エンコーディング名や共通タグライブラリの指定などを省略することが出来ます。

taglib

このアプリケーションで使用する全てのJSPにデフォルトで設定するタグライブラリ群を定義します。

taglib-uri

タグライブラリのURIを記述します。

taglib-location

このタグライブラリに対応する設定ファイル(通用は拡張子tld)が格納されているパスを記述します。

jsp-property-group

このアプリケーションで使用するJSPにデフォルトで設定するプロパティ群を定義します。

url-pattern

このプロパティ群を適用するURLパターンを定義します。
ワイルドカード(*)が使用できます。
複数定義可能です。

el-ignored

EL式の有効/無効を定義します。デフォルトは false (EL式は有効)です。

page-encoding

JSPファイルの文字エンコーディングを定義します。

scripting-invalid

scripting の有効/無効を定義します。デフォルトは false (scriptingは有効)です。
scripting とは、

<%
  int value = 0;
%>

のようにJSP内にJavaコードを記述する手法のことです。
なるべくなら、全てのページで scripting は無効にしましょう。
無効にしたページで scripting を使用すると JasperException が発生します。

is-xml

ページがXMLで記述されているかどうかを定義します。

include-prelude

デフォルトでページの先頭にincludeするファイルのパスを記述します。
複数定義可能です。

include-coda

デフォルトでページの最後にincludeするファイルのパスを記述します。
複数定義可能です。



ページの先頭へ

taglib

JSPタグライブラリの設定を記述します。
この要素は複数配置することが可能です。
次の子要素を持ちます。

taglib-uri

タグライブラリのURIを記述します。JSPファイル側の記述ではこのURIを使うことになります。

taglib-location

このタグライブラリに対応する設定ファイルが格納されているパスを記述します。
設定ファイルに関してはJSPタグライブラリ設定ファイル構文解析を参照して下さい。



ページの先頭へ

resource-env-ref

<resource-env-ref>
    <resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>

リソース参照の定義を記述します。
詳細は不明です。



ページの先頭へ

resource-ref

<resource-ref>
    <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

リソースの定義を記述します。
この要素は複数配置することが可能です。
次の子要素を持ちます。

description

このリソースの説明文を記述します。

res-ref-name

server.xmlで定義したResource要素のname属性値に合わせます。

res-type

server.xmlで定義したResource要素のtype属性値に合わせます。

res-auth

server.xmlで定義したResource要素のauth属性値に合わせます。
Application / Container のいずれかを使用できます。

res-sharing-scope

このリソースが共有可能かどうかを定義します。
Shareable / Unshareable のいずれかを使用できます。
デフォルトは Shareable(共有可能) です。



ページの先頭へ

message-destination

詳細は不明です。



ページの先頭へ

message-destination-ref

<message-destination-ref>
    <message-destination-ref-name>jms/StockQueue
    </message-destination-ref-name>
    <message-destination-type>javax.jms.Queue
    </message-destination-type>
    <message-destination-usage>Consumes
    </message-destination-usage>
    <message-destination-link>CorporateStocks
    </message-destination-link>
</message-destination-ref>

詳細は不明です。



ページの先頭へ

service-ref

詳細は不明です。



ページの先頭へ

security-constraint

Tomcatによるアクセス制限を掛ける際に使用する要素です。
以下の子要素を持ちます。

display-name

この要素に関する簡易名を記述します。

web-resource-collection

アクセス制限を掛けるリソースの集合を定義します。
リソースとはWebアプリケーションに含まれるあらゆるファイルを指します。
この要素は最低1つ以上記述する必要があります。
以下の子要素を持ちます。

web-resource-name

この項目に対応するリソース名を記述します(必須)。
任意の文字列で構わないはずです。

description

この要素の説明文を記述します。

url-pattern

この項目に対応するリソースをURLで記述します。
いくつか記述方法の例を挙げてみます。

アプリケーション全体

アプリケーション全体を指定する場合は、/ と記述します。

ファイル単位

単一のリソースを指定する場合は、/folder/file1 のように記述します。

拡張子別

特定の拡張子を持つ全てのリソースを指定する場合は、*.jsp のように記述します。

ディレクトリ

特定のディレクトリ以下の全リソースを指定する場合は、/folder/* のように記述します。

{*})) は万能ワイルドカードではありません。
ば、 /pre*.do/folder/*.jsp のような使い方は出来ません。

http-method

この項目に適用されるHTTPメソッドを定義します。
省略すると、全てのHTTPメソッドがこの項目に適用されます。
この要素は複数記述することが可能です。

以下に、使用できるHTTPメソッドの一覧を示します。
GET / POST / PUT / DELETE / HEAD / OPTIONS / TRACE

auth-constraint

このアプリケーションから利用するロールの集合を定義します。

description

ロール集合の説明文を記述します。

role-name

ロール名を記述します。この要素は複数記述することが可能です。
* と記述すると、全てのロールが使用可能になります。

user-data-constraint

クライアント - サーバ(コンテナ)間のデータ通信を
どのように保護するのかを指定します。(詳細は不明です)
以下の子要素を持ちます。

description

この要素の説明文を記述します。

transport-guarantee

データ通信の方法を記述します。
NONE / INTEGRAL / CONFIDENTIAL のいずれかを指定できます。



ページの先頭へ

login-config

ログイン方法を定義します。
ユーザがログインするタイミングは、
アクセス制限のあるリソースにアクセスしようとした時です。

auth-method

ログイン時の認証に使われるメカニズムを指定します。
BASIC, DIGEST, FORM, CLIENT-CERT のいずれかを記述します。
login-config 要素を省略すると FORM がデフォルトで使用されます。

  • BASIC

    BASIC認証が使われます。
    ダイアログが開き、ユーザ名とパスワードの入力を求めます。

  • DIGEST

    DIGEST認証が使われます。
    それ以外は BASIC と同じです。

  • FORM

    html又はjspで記述された任意のフォーム画面を使用します。
    使用する画面は後述する form-login-config でカスタマイズできます。

realm-name

認証Realm名を記述します。任意の文字列で構いません。

form-login-config

ログイン / エラー画面を指定します。
この要素は auth-methodFORM の場合だけ有効になります。
以下の子要素を持ちます。

form-login-page

ログイン画面のURLを記述します。デフォルトは /login.jsp です。

form-error-page

エラー画面のURLを記述します。デフォルトは /error.jsp です。



ページの先頭へ

security-role

<security-role>
  <description>
    This role includes all employees who are authorized
    to access the employee service application.
  </description>
  <role-name>employee</role-name>
</security-role>

セキュリティ・ロール情報を記述します。この要素は複数配置することが可能です。

ロールとは、データベース等で使用される「権限」によく似たものです。

次の子要素を持ちます。

description

このロールの説明文を記述します。

role-name

このアプリケーションで利用するロール名を記述します。



ページの先頭へ

env-entry

アプリケーションの環境変数に関する記述です。
この要素は複数配置することが可能です。
次の子要素を持ちます。

description

この環境変数の説明文を記述します。

env-entry-name

この環境変数の名前を記述します。

env-entry-value

この環境変数の値を記述します。

env-entry-type

この環境変数の型を完全限定名で記述します。
使用できる型は、java.lang.Boolean, Byte, Character, String, Short, Integer, Long, Float, Double です。



ページの先頭へ

ejb-ref

EJB参照に関する記述です。
この要素は複数配置することが可能です。
次の子要素を持ちます。

description

このEJB参照の説明文を記述します。

ejb-ref-name

このEJB参照の名前を記述します。
これはサーブレットのコードが参照を得るときに利用するJNDI名です。

ejb-ref-type

このEJB参照の型(クラス名)を記述します。

home

このEJBのhomeインターフェイス名を完全限定名で記述します。

remote

このEJBのremoteインターフェイス名を完全限定名で記述します。

ejb-link

用途不明です。



ページの先頭へ

ejb-local-ref

EJBローカル参照に関する記述です。J2EE 1.3で利用可能な要素です。
この要素は複数配置することが可能です。
次の子要素を持ちます。

description

このEJB参照の説明文を記述します。

ejb-ref-name

このEJB参照の名前を記述します。
これはサーブレットのコードが参照を得るときに利用するJNDI名です。
ejb/ というプレフィックスを付けることが推奨されています。

ejb-ref-type

Enterprise Bean の型を記述します。
Entity / Session のいずかを取ります。

local-home

local homeインターフェイス名を完全限定名で記述します。

local

localインターフェイス名を完全限定名で記述します。

ejb-link

用途不明です。



ページの先頭へ

locale-encoding-mapping-list

ロケールとエンコーディングの対応表を指定します。
これにより、柔軟な多言語対応が実現できます。

<locale-encoding-mapping-list>
  <locale-encoding-mapping>
    <locale>ja</locale>
    <encoding>EUC-JP</encoding>
  </locale-encoding-mapping>
</locale-encoding-mapping-list>
locale-encoding-mapping

ロケールに対応するエンコーディングを指定します。
この要素は複数配置することが可能です。

locale

ロケール名を指定します。

encoding

ロケールに対応するエンコーディング名を指定します。

ページの先頭へ