minimize

事業拡大のため、新しい仲間を募集しています。
→詳しくはこちら

Tomcatのweb.xmlの構文を解析します。
web-app_2_2.dtd (J2EE 1.2) 及び web-app_2_3.dtd (J2EE 1.3)
に対応しています。

$TOMCAT_HOME/conf/web.xml に全アプリケーション共通の設定を記述し、
各Webアプリケーション毎の WEB-INF/web.xml にはアプリケーション個別の設定を記述します。

前者の方は修正したらTomcatの再起動が必要ですが、
後者の方は修正したらWebアプリケーション・マネージャを利用することによって
Tomcatの再起動無しにその修正内容を反映させる事ができます。

web-app

ルートとなる要素は常にweb-appとなります。
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とフィルターの対応(マッピング)方法を記述します。J2EE 1.3で利用可能な要素です。
この要素は複数配置することが可能です。
以下の子要素を持ちます。

filter-name

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

url-pattern

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

servlet-name

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

listener

Listener定義を記述します。J2EE 1.3で利用可能な要素です。
この要素は複数配置することが可能です。
唯一の子要素を持ちます。

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 要素がある場合、
それらを初期化する順序を指定します。値は、正の整数である必要があります。
省略した場合、このサーブレットが初期化されるタイミングは予測できません。

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を記述します。

taglib

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

taglib-uri

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

taglib-location

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

resource-env-ref

リソース参照の定義を記述します。J2EE 1.3で利用可能な要素です。
詳細は不明です。

resource-ref

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

description

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

res-ref-name

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

res-type

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

res-auth

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

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メソッドとは、GETPOST などのことです。
省略すると、全てのHTTPメソッドがこの項目に適用されます。
この要素は複数記述することが可能です。

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

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

ロールとは、データベース等で使用される「権限」によく似たものです。
ロールの使い方は、ユーザ認証のところを参考にして下さい。

次の子要素を持ちます。

description

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

role-name

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

env-entry

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

description

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

env-entry-name

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

env-entry-value

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

env-entry-type

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

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-ref-type

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

home

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

remote

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

ejb-link

用途不明です。

FORMによるログインについて

ログイン時の認証に FORM を使ったときの動作について説明します。
ユーザが security-constraint 要素の web-resource-collection で定義したリソースに
アクセスしようとすると、form-login-page で指定したURLにジャンプします。

このログイン画面は各自自作する必要があります。
$TOMCAT_HOME/server/webapps/admin/login.jsp を参考にすれば判ると思います。
ユーザは、フォームにユーザ名とパスワードを入力してSUBMITボタンを押します。
ここで指定したユーザは、security-constraint / auth-constraint 要素内の
role-name 要素で記述されたロールを持つユーザである必要があります。
ユーザとロールの一覧は、設定ファイルに記述します。
デフォルトでは $TOMCAT_HOME/conf/tomcat-users.xml です。

ログイン認証に成功すると、目的のリソース(のURL)にジャンプします。
一旦認証が成功すれば、以降はブラウザを閉じるまでこの認証は有効になります。
認証に失敗すると、form-error-page で指定したURLにジャンプします。