設定 web.xml 部署作業描述元

只有在將 Java 應用程式部署至包含 Eclipse Jetty 9/ Servlet 3 伺服器的執行階段時，才會使用 web.xml 檔案。詳情請參閱 Eclipse Jetty 9.3 執行階段。

Java 網路應用程式使用部署作業描述元檔案，就能判斷網址對應 Servlet 的方式、需要驗證的網址，以及其他資訊。此檔案的名稱為 web.xml，存放在 WEB-INF/ 目錄的應用程式 WAR 中。web.xml 屬於網路應用程式的 Servlet 標準。

如要進一步瞭解 web.xml 標準，請參閱 Servlet 規格。

關於部署描述元

網路應用程式的部署作業描述元將描述應用程式的類別、資源和設定，以及網頁伺服器如何使用它們提供網路要求。當網頁伺服器收到對應用程式的要求時，伺服器將使用部署作業描述元，將要求的網址對應至負責處理該要求的程式碼。

部署描述元是名為 web.xml 的檔案，存放在 WEB-INF/ 目錄下應用程式的 WAR 中。該檔案是 XML 檔案，其根元素為 <web-app>。

以下是簡單的 web.xml 範例，可將所有網址路徑 (/*) 對應至 Servlet 類別 =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>

Servlet 和網址路徑

web.xml 定義網址路徑與 Servlet 之間的對應，其中 Servlet 可處理具有這些路徑的要求。網路伺服器會利用這項設定，指定什麼樣的要求應交給哪一個 Servlet 處理，並呼叫與要求方法對應的類別方法 (例如 HTTP GET 要求的 doGet() 方法)。

如要將網址對應至 Servlet，您要使用 <servlet> 元素宣告 Servlet，然後使用 <servlet-mapping> 元素定義從網址路徑到 Servlet 宣告的對應。

<servlet> 元素可宣告 Servlet，其中包括檔案中的其他元素用來參照 Servlet 的名稱、用於 Servlet 的類別，以及初始化參數。您可以使用擁有不同初始化參數 (Initialization Parameter) 的相同類別，宣告多個 Servlet。在所有部署作業描述元中，每個 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> 元素可指定網址模式與所宣告 Servlet 的名稱，且該名稱將用於網址符合模式的要求。網址格式可以在格式的開頭或結尾處使用星號 (*)，藉此表示零個或多個任何字元。(此標準不支援在字串中間使用萬用字元，也不允許在單一格式中使用多個萬用字元。)這個格式符合完整的網址路徑，而且此網址路徑在網域名稱的開頭和結尾均使用正斜線 (/)。

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

在這個範例中，TeamServlet 類別會處理 http://www.example.com/blue/teamProfile 網址的要求，其中 teamColor 參數等於 blue，bgColor 參數等於 #0000CC。Servlet 可以使用 ServletRequest 物件的 getPathInfo() 方法，取得萬用字元比對的網址路徑部分。

Servlet 可以存取其初始化參數，方法是使用自己的 getServletConfig() 方法取得 Servlet 設定，然後使用參數名稱做為引數，針對設定物件呼叫 getInitParameter() 方法。

        String teamColor = getServletConfig().getInitParameter("teamColor");

JSP

應用程式可以使用 JavaServer Page (JSP) 實作網頁。JSP 是透過靜態內容 (例如 HTML)，搭配 Java 程式碼所定義的 Servlet。

App Engine 支援 JSP 的自動編譯與網址對應。在應用程式的 WAR 中 (在 WEB-INF/ 之外)，檔名結尾是 .jsp 的 JSP 檔案將自動編譯為 Servlet 類別，並對應至網址路徑，此路徑相當於 JSP 檔案至 WAR 根目錄的路徑。舉例來說，如果應用程式在 WAR 的 register/ 子目錄中，有一個名稱是 start.jsp 的 JSP 檔案，App Engine 將編譯該檔案並將其對應至網址路徑 /register/start.jsp。

如要進一步控管將 JSP 對應至網址的方式，可以透過在部署作業描述元中使用 <servlet> 元素宣告的方式明確指定對應。您可以使用 JSP 檔案至 WAR 根目錄的路徑指定 <jsp-file> 元素，而不是 <servlet-class> 元素。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>

歡迎檔案清單

當您網站的網址代表 WAR 的靜態檔案路徑或 JSP 路徑時，建議您讓目錄的路徑發揮一些作用。為取得帳戶密碼相關資訊而造訪網址路徑 /help/accounts/password.jsp 的使用者，可能會嘗試造訪 /help/accounts/，尋找介紹帳戶系統說明文件的頁面。使用者存取代表 WAR 子目錄的路徑 (尚未明確對應至 Servlet) 時，部署作業描述元可以指定伺服器應該嘗試的檔案名稱清單。Servlet 標準將該清單稱為「歡迎檔案清單」。

舉例來說，如果使用者存取網址路徑 /help/accounts/，部署描述元中的下列 <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>

篩選器

篩選器是一種類別，它跟 Servlet 一樣會根據要求來採取行動，但能允許其他篩選器或 Servlet 繼續處理同一個要求。篩選器可以執行輔助作業，例如記錄、執行特殊驗證檢查，或在呼叫 Servlet 之前註解要求或回應物件。篩選器可讓您從部署作業描述元，編寫要求處理工作。

篩選器類別會實作 javax.servlet.Filter 介面，包括 doFilter() 方法。下方的簡易篩選器實作將記錄一則訊息，並向鏈結下方傳送控制項，其中可能包括其他篩選器或 Servlet，如部署作業描述元所述：

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() {}

}

與 Servlet 類似，您可以使用 <filter> 元素宣告篩選器，然後使用 <filter-mapping> 元素將其對應至網址模式，藉此在部署作業描述元中設定篩選器。您也可以將篩選條件直接對應至其他的 Servlet。

<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> 元素，或是與宣告 Servlet 名稱相符的 <servlet-name> 元素，用於在每次呼叫 Servlet 時套用篩選器。

    <!-- 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 狀態碼時，或在 Servlet 引發特定的 Java 例外狀況時，可以顯示替代頁面位置。

<error-page> 元素包含 <error-code> 元素，其擁有 HTTP 錯誤代碼值 (例如 500)；或包含 <exception-type> 元素，其擁有預期例外狀況的類別名稱 (例如 java.io.IOException)。亦包含 <location> 元素，其擁有錯誤發生時要顯示的資源網址路徑。

    <error-page>
        <error-code>500</error-code>
        <location>/errors/servererror.jsp</location>
    </error-page>

不支援的 web.xml 功能

App Engine 不支援下列 web.xml 功能：

  • App Engine 支援用於 Servlet 宣告的 <load-on-startup> 元素。不過，載入必須等到網頁伺服器執行個體處理第一個要求的期間 (而非之前)，才會實際發生。
  • 某些部署作業描述元的元素可以接受使用者可理解的顯示名稱、說明和圖示，以在 IDE 中使用。App Engine 不使用這些元素，且會加以忽略。
  • App Engine 不支援 JNDI 環境變數 (<env-entry>)。
  • App Engine 不支援 EJB 資源 (<resource-ref>)。
  • 系統無法在刪除 Servlet、Servlet 結構定義或篩選器時發出通知。
  • 系統會忽略 <distributable> 元素。
  • 系統不支援使用 <run-at> 的 Servlet 排程。
  • 系統不支援安全性限制：如要瞭解對等功能，請參閱「使用用戶端程式庫對 Cloud 服務進行驗證」。
  • web.xml 不支援機密性。