web.xml ファイルは、Java アプリを Eclipse Jetty 9 / servlet 3 サーバーを含むランタイムにデプロイする際にのみ使用されます。詳細については、Eclipse Jetty 9.3 ランタイムをご覧ください。
Java ウェブ アプリケーションでは、デプロイ記述子ファイルを使用して、URL からサーブレットへのマッピング、認証が必要な URL などの情報を決定します。このファイルの名前は web.xml で、アプリの WAR の WEB-INF/ ディレクトリにあります。web.xml は、ウェブ アプリケーション用のサーブレット標準の一部です。
web.xml 標準の詳細については、サーブレットの仕様をご覧ください。
デプロイ記述子について
ウェブ アプリケーションのデプロイ記述子では、アプリケーションのクラス、リソース、構成のほか、ウェブサーバーがこれらを使用してウェブ リクエストを処理する方法を記述します。ウェブサーバーは、アプリケーションからのリクエストを受信すると、デプロイ記述子を使用して、リクエストを処理するコードにリクエストの URL をマッピングします。
デプロイ記述子のファイル名は web.xml です。これは、アプリの WAR の WEB-INF/ ディレクトリにあります。これはルート要素が <web-app> の XML ファイルです。
次に示す web.xml の簡単な例では、すべての URL パス（/*）をサーブレット クラス mysite.server.ComingSoonServlet にマッピングしています。
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<servlet>
<servlet-name>comingsoon</servlet-name>
<servlet-class>mysite.server.ComingSoonServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>comingsoon</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
サーブレットと URL パス
web.xml では、URL パスと、そのパスでリクエストを処理するサーブレットのマッピングを定義します。ウェブサーバーは、この構成を使用して、指定されたリクエストを処理するサーブレットを特定し、リクエストのメソッドに対応するクラスメソッド（例: HTTP GET リクエストの場合は doGet() メソッド）を呼び出します。
URL をサーブレットにマッピングするには、<servlet> 要素を使用してサーブレットを宣言してから、<servlet-mapping> 要素を使用して URL パスからサーブレット宣言へのマッピングを定義します。
<servlet> 要素では、ファイル内の他の要素がサーブレットを参照するのに使用する名前、サーブレットで使用するクラス、初期化パラメータなどを指定して、サーブレットを宣言します。異なる複数の初期化パラメータを使用して、同じクラスの複数のサーブレットを宣言できます。各サーブレットの名前はデプロイ記述子全体で一意でなければなりません。
<servlet>
<servlet-name>redteam</servlet-name>
<servlet-class>mysite.server.TeamServlet</servlet-class>
<init-param>
<param-name>teamColor</param-name>
<param-value>red</param-value>
</init-param>
<init-param>
<param-name>bgColor</param-name>
<param-value>#CC0000</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>blueteam</servlet-name>
<servlet-class>mysite.server.TeamServlet</servlet-class>
<init-param>
<param-name>teamColor</param-name>
<param-value>blue</param-value>
</init-param>
<init-param>
<param-name>bgColor</param-name>
<param-value>#0000CC</param-value>
</init-param>
</servlet>
<servlet-mapping> 要素では、URL パターンと、そのパターンと一致する URL のリクエストで使用する宣言済みのサーブレットの名前を指定します。URL パターンでは、パターンの先頭と末尾にアスタリスク（*）を使用できます。アスタリスクは、0 個以上の任意の文字を表します。標準仕様では、文字列の途中でワイルドカードを使用することや、1 つのパターン内で複数のワイルドカードを使用することはできせん。パターンは URL の完全なパスと照合されるので、スラッシュ（/）で開始し、ドメイン名の後にスラッシュを含めます。
<servlet-mapping>
<servlet-name>redteam</servlet-name>
<url-pattern>/red/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>blueteam</servlet-name>
<url-pattern>/blue/*</url-pattern>
</servlet-mapping>
上の例では、URL http://www.example.com/blue/teamProfile のリクエストは、TeamServlet クラスで処理され、teamColor パラメータは blue、bgColor パラメータは #0000CC に設定しています。サーブレットは、ワイルドカードに一致した URL パスの部分を ServletRequest オブジェクトの getPathInfo() メソッドを使用して取得できます。
サーブレットが初期化パラメータにアクセスするには、サーブレット自体の getServletConfig() メソッドを使用してサーブレットの構成を取得してから、その構成オブジェクトに対して、パラメータ名を引数として、getInitParameter() メソッドを呼び出します。
String teamColor = getServletConfig().getInitParameter("teamColor");
JSP
アプリは、JavaServer Pages（JSP）を使用して、ウェブページを実装できます。JSP とは、静的コンテンツ（HTML など）と Java コードを組み合わせて定義されるサーブレットです。
App Engine は、JSP の自動コンパイルと URL マッピングをサポートしています。アプリケーションの WAR 内（WEB-INF/ の外）にある JSP ファイルで、ファイル名が .jsp で終わるものは自動的にサーブレット クラスにコンパイルされ、WAR のルートから JSP ファイルへのパスと同じ URL パスにマッピングされます。たとえば、アプリの WAR の register/ というサブディレクトリに start.jsp という JSP ファイルが含まれている場合、App Engine はそのファイルをコンパイルし、URL パス /register/start.jsp にマッピングします。
JSP の URL へのマッピングを詳細に制御する必要がある場合は、デプロイ記述子で <servlet> 要素を使用して宣言することで、マッピングを明示的に指定できます。<servlet-class> 要素の代わりに、<jsp-file> 要素に、WAR ルートから JSP ファイルへのパスを指定します。JSP 用の <servlet> サーブレット要素に初期化パラメータを指定できます。
<servlet>
<servlet-name>register</servlet-name>
<jsp-file>/register/start.jsp</jsp-file>
</servlet>
<servlet-mapping>
<servlet-name>register</servlet-name>
<url-pattern>/register/*</url-pattern>
</servlet-mapping>
<taglib> 要素を使用して、JSP タグライブラリをインストールできます。タグライブラリには、JSP タグライブラリ記述子（TLD）ファイルへのパス（<taglib-location>）と、JSP が読み込むライブラリの選択に使用する URI（<taglib-uri>）が含まれています。App Engine には JavaServer Pages 標準タグライブラリ（JSTL）が用意されているので、このライブラリをインストールする必要はありません。
<taglib>
<taglib-uri>/escape</taglib-uri>
<taglib-location>/WEB-INF/escape-tags.tld</taglib-location>
</taglib>
ウェルカム ファイル リスト
サイトの URL が WAR 内の静的ファイルまたは JSP へのパスを表している場合、ディレクトリへのパスにも工夫をすることをおすすめします。たとえば、ユーザーがアカウントのパスワードについての情報を取得するために URL パス /help/accounts/password.jsp にアクセスするときに、/help/accounts/ にアクセスしてアカウント システムのドキュメント紹介ページを検索する場合があります。サーブレットに明示的にマッピングされていない WAR サブディレクトリを表すパスにユーザーがアクセスしようとしたときに、サーバーがアクセスを試みるファイル名のリストを、デプロイ記述子に指定することができます。サーブレット標準ではこのリストを「ウェルカム ファイル リスト」と呼んでいます。
たとえば、ユーザーが URL パス /help/accounts/ にアクセスすると、サーバーは URL が見つからないと報告する前に、デプロイ記述子内の次の <welcome-file-list> 要素に基づき help/accounts/index.jsp や help/accounts/index.html を探します。
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
フィルタ
「フィルタ」はリクエストに対しサーブレットのように動作するクラスですが、リクエストの処理を他のフィルタやサーブレットが引き継ぐことができます。フィルタは、ロギング、特別な認証チェック、リクエスト オブジェクトやレスポンス オブジェクトのアノテーションなどの補助的なタスクを、サーブレットを呼び出す前に実行できます。フィルタを使用して、デプロイ記述子からリクエスト処理タスクを作成できます。
フィルタクラスは javax.servlet.Filter インターフェースを実装しています。このインターフェースには doFilter() メソッドが含まれます。次の例では、メッセージをログに記録してから制御を連鎖的に渡す簡単なフィルタ実装を示します。デプロイ記述子に記載されている場合は、他のフィルタやサーブレットを含めることができます。
package mysite.server;
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
log.warning("Log filter processed a " + getFilterConfig().getInitParameter("logType")
+ " request");
filterChain.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void init(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
public void destroy() {}
}
デプロイ記述子でフィルタを構成するには、サーブレットと同様に、<filter> 要素を使用してフィルタを宣言し、<filter-mapping> 要素を使用して URL パターンにマッピングします。フィルタを他のサーブレットに直接マッピングすることもできます。
<filter> 要素には、<filter-name>、<filter-class>、省略可能な <init-param> 要素を指定します。
<filter>
<filter-name>logSpecial</filter-name>
<filter-class>mysite.server.LogFilterImpl</filter-class>
<init-param>
<param-name>logType</param-name>
<param-value>special</param-value>
</init-param>
</filter>
<filter-mapping> 要素には、宣言したフィルタの名前に一致する <filter-name> のほか、<url-pattern> 要素（URL にフィルタを適用します）または宣言したサーブレットの名前に一致する <servlet-name> 要素（サーブレットが呼び出されたときにフィルタを適用します）のいずれかを指定します。
<!-- Log for all URLs ending in ".special" -->
<filter-mapping>
<filter-name>logSpecial</filter-name>
<url-pattern>*.special</url-pattern>
</filter-mapping>
<!-- Log for all URLs that use the "comingsoon" servlet -->
<filter-mapping>
<filter-name>logSpecial</filter-name>
<servlet-name>comingsoon</servlet-name>
</filter-mapping>
エラーハンドラ
エラーが発生したときにサーバーがユーザーに送信する内容を、デプロイ記述子を使用してカスタマイズできます。ある特定の HTTP ステータス コードを送信するときや、サーブレットが特定の Java 例外を送出するときに、サーバーで代替ページの場所を表示することができます。
<error-page> 要素には、HTTP エラーコード値（500 など）を含む <error-code> 要素を指定するか、想定される例外のクラス名（java.io.IOException など）を含む <exception-type> 要素を指定します。また、エラーが発生したときに表示するリソースの URL パスを含む <location> 要素も指定します。
<error-page>
<error-code>500</error-code>
<location>/errors/servererror.jsp</location>
</error-page>
サポートされていない web.xml の機能
次の web.xml 機能は App Engine ではサポートされていません。
- App Engine では、サーブレットの宣言で
<load-on-startup>要素がサポートされています。しかし実際には、最初のリクエストの前ではなく、ウェブサーバー インスタンスによって最初のリクエストが処理されるときに読み込みが行われます。 - デプロイ記述子の一部の要素では、統合開発環境（IDE）で使用するために、人間が認識可能な表示名、説明、アイコンを使用できますが、App Engine ではこれらは使用されず、無視されます。
- App Engine では JNDI 環境変数（
<env-entry>）はサポートされていません。 - App Engine では EJB リソース（
<resource-ref>）はサポートされていません。 - サーブレットやサーブレット コンテキスト、フィルタの破棄の通知はサポートされていません。
<distributable>要素は無視されます。<run-at>を使用したサーブレットのスケジューリングはサポートされていません。- セキュリティ制限はサポートされていません。同等の機能については、クライアント ライブラリを使用して Cloud サービスの認証を行うをご覧ください。
- CONFIDENTIAL は
web.xmlではサポートされていません。