部署描述元：web.xml

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

如需 web.xml 標準的詳細資訊，請參閱 Metawerx web.xml 參照 wiki、WebLogic web.xml 元素參照以及 servlet 規格。

• 關於部署描述元
• Servlet 和 URL 路徑
• JSP
• 安全性和驗證
• 安全 URL
• Welcome 檔案清單
• 篩選器
• 錯誤處理常式
• 尚未支援的 web.xml 功能

關於部署描述元

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

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

下方的簡單 web.xml 範例會將所有 URL 路徑 (/*) 對應至 servlet 類別 mysite.server.ComingSoonServlet：

<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <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 和 URL 路徑

web.xml 定義 URL 路徑和使用這些路徑處理要求的 servlet 之間的對應。網頁伺服器會使用這個設定，識別負責處理指定要求的 servlet，並呼叫要求方法的相應類別方法 (例如，HTTP GET 要求的 doGet() 方法)。

如要將 URL 對應至 servlet，請透過 <servlet> 元素宣告 servlet，再透過 <servlet-mapping> 元素定義從 URL 路徑到 servlet 宣告的對應。

<servlet> 元素會宣告 servlet，包括檔案其他元素參考 servlet 時所使用的名稱、用於 servlet 的類別，以及初始化參數。您可以使用擁有不同初始化參數的相同類別來宣告多個 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> 元素會指定 URL 模式和宣告的 servlet 名稱，供 URL 符合模式的要求使用。URL 模式可以在模式的開頭或結尾處使用星號 (*)，藉此表示零或多個的任何字元。 (此標準不支援在字串中間使用萬用字元，也不允許在單一模式中使用多個萬用字元)。這個模式符合完整的 URL 路徑，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。這個 servlet 可以透過 ServletRequest 物件的 getPathInfo() 方法，取得符合萬用字元的部分 URL 路徑。

注意：靜態檔案 (逐一提供給使用者的檔案，例如影像、CSS 或 JavaScript) 是由部署描述元中所提及的路徑另行處理。無論部署描述元中的 servlet 和篩選器對應為何，檔案將由符合 WAR 靜態檔案路徑的 URL 路徑提供。您可以使用 appengine-web.xml 檔案，將檔案從靜態檔案中排除。

Servlet 可以使用本身的 getServletConfig() 方法，取得其 servlet 設定，然後使用參數名稱做為引數，在設定物件上呼叫 getInitParameter() 方法，藉此存取其初始化參數。

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

JSP

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

「應用服務引擎」支援 JSP 的自動編譯與 URL 對應。在應用程式 WAR 中 (在 WEB-INF/ 外面)，檔名結尾為 .jsp 的 JSP 檔案將自動編譯成 servlet 類別，並對應至與 WAR 根目錄的 JSP 檔案路徑相等的 URL 路徑。舉例來說，如果應用程式在 WAR 的 register/ 子目錄包含一個名稱為 start.jsp 的 JSP 檔案，「應用服務引擎」會加以編譯，並將它對應至 URL 路徑 /register/start.jsp。

如要進一步控制 JSP 與 URL 的對應方式，您可以透過部署描述元中的 <servlet> 元素宣告，以明確指定對應。您不需要指定 <servlet-class> 元素，反之，請使用 WAR 根目錄的 JSP 檔案路徑指定 <jsp-file> 元素。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 標記程式庫描述元 (Tag Library Descriptor，TLD) 檔案的路徑 (<taglib-location>)，以及 JSP 用於選取載入程式庫的 URI (<taglib-uri>)。請注意，「應用服務引擎」提供 JavaServer Pages Standard Tag Library (JSTL)，因此您不需要安裝。

    <taglib>
        <taglib-uri>/escape</taglib-uri>
        <taglib-location>/WEB-INF/escape-tags.tld</taglib-location>
    </taglib>

安全性和驗證

「應用服務引擎」可以使用「Google 帳戶」驗證使用者。應用程式可以使用 Google Accounts API 偵測使用者是否已登入，取得目前登入使用者的電子郵件地址，以及產生登入和登出 URL。應用程式也可以使用部署描述元，根據 Google 帳戶指定 URL 路徑存取限制。

<security-constraint> 元素會針對符合特定模式的 URL 定義安全限制。如果使用者存取設有安全限制的 URL 路徑，卻尚未登入，「應用服務引擎」會將使用者重新導向「Google 帳戶」登入頁面。「Google 帳戶」會在使用者成功登入或註冊新帳戶之後，將使用者重新導向應用程式 URL。應用程式不需要執行任何其他步驟，即可確保只有登入使用者才能存取 URL。

安全限制包括一項驗證限制，當中會指定可以存取路徑的「Google 帳戶」使用者。如果驗證限制將使用者角色指定為 *，則所有透過「Google 帳戶」登入的使用者均可存取 URL。如果驗證限制將使用者角色指定為 admin，則只有註冊的應用程式開發人員 (管理員) 可以存取 URL。admin 角色可讓您在網站上輕輕鬆鬆建置管理員專區。

    <security-constraint>
        <web-resource-collection>
            <url-pattern>/profile/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>*</role-name>
        </auth-constraint>
    </security-constraint>

    <security-constraint>
        <web-resource-collection>
            <url-pattern>/admin/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
    </security-constraint>

「應用服務引擎」不支援在部署描述元中使用自訂安全角色 (<security-role>) 或替代驗證機制 (<login-config>)。

安全限制會套用至靜態檔案和 servlet。

安全 URL

「Google 應用服務引擎」是透過使用 *.appspot.com 網域的 URL HTTPS 支援安全連線。當要求透過 HTTPS 存取 URL 時，要求資料和回應資料會由傳送者在傳輸之前加密，然後由接收者在收到之後解密。安全連線對於保護客戶資料 (例如聯絡人資訊、密碼以及私人訊息) 十分有用。

注意：「Google 應用服務」網域目前不支援 HTTPS。HTTPS 支援僅限於透過 *.appspot.com 網域存取的應用程式。存取「Google 應用服務」網域上的 HTTPS URL 時，將傳回「找不到主機」錯誤，而透過 HTTP 存取處理常式只接受 HTTPS (請參閱下方) 的 URL 時，將傳回 HTTP 403 的「禁止瀏覽」錯誤。您可以透過 *.appspot.com 網域的 HTTPS URL，以使用安全功能，至於網站的其餘部分，則可以透過「應用服務」網域和 HTTP 連結。

您必須先使用 <ssl-enabeld>true</ssl-enabled> 元素，在應用程式的 appengine-web.xml 檔案中啟用安全 URL，然後才能使用應用程式的安全 URL。如需這個檔案的詳細資訊，請參閱「應用程式設定：啟用安全 URL」。

如要宣告 URL 應該使用 HTTPS，您可以在部署描述元 (如「安全性和驗證」所述) 設定安全限制 ，其中 <user-data-constraint> 的 <transport-guarantee> 設定為 CONFIDENTIAL，如下所示：

    <security-constraint>
        <web-resource-collection>
            <url-pattern>/profile/*</url-pattern>
        </web-resource-collection>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

如果要求試圖透過 HTTP (不安全連線) 存取 transport guarantee 為 CONFIDENTIAL 的 URL，將被自動重新導向使用 HTTPS 的相同 URL。

相較於不安全的連線，安全連線耗用較多的 CPU 和頻寬，因此成本較高。安全連線的速度也比較緩慢。

任何 URL 都可以使用 CONFIDENTIAL transport guarantee，包括 JSP 和靜態檔案。

開發網頁伺服器不支援 HTTPS 連線。它會忽略 transport guarantee，因此開發網頁伺服器的定期 HTTP 連線可以測試專用於 HTTPS 的路徑。

當您透過已建立版本的 appspot.com URL (例如 https://1.latest.app-id.appspot.com/) 測試應用程式的 HTTPS 處理常式時，瀏覽器將警告您該網域路徑的 HTTPS 憑證尚未獲得簽署。如果您接受該網域的憑證，將成功載入網頁。 使用者在存取 https://app-id.appspot.com/ 時，不會看到憑證警告。

無論應用程式的 URL 設定為何，「Google 帳戶」一律採用安全連線執行登入和登出。

如上所述，安全限制會套用至靜態檔案和 servlet。這包括 transport guarantee。

Welcome 檔案清單

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

舉例來說，如果使用者存取 URL 路徑 /help/accounts/，下列的部署描述元 <welcome-file-list> 元素將指示伺服器先檢查 help/accounts/index.jsp 和 help/accounts/index.html，再回報 URL 是否存在：

    <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.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class LogFilterImpl implements Filter {
    private FilterConfig filterConfig;
    private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());

    public void doFilter(HttpServletRequest request,
                         HttpServletResponse response,
                         FilterChain filterChain)
            throws IOException, ServletException {
        log.info("Log filter processed a " +
                 getServletConfig().getInitParameter("logType") +
                 " request");

        filterConfig.doFilter(request, response);
    }

    public FilterConfig getFilterConfig() {
        return filterConfig;
    }
    public void setFilterConfig(FilterConfig filterConfig) {
        this.filterConfig = filterConfig;
    }
}

與 servlet 類似，您可以在部署描述元中設定篩選器，方法是使用 <filter> 元素宣告篩選器，然後使用 <filter-mapping> 元素將它對應至 URL 模式。您也可以將篩選器直接對應至其他的 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-name> 元素；前者會套用篩選器至 URL，後者則會比對宣告的 servlet 名稱，供呼叫 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> 元素或 <exception-type> 元素；前者帶有 HTTP 錯誤代碼值 (例如 500)，後者則帶有預期例外狀況的類別名稱 (例如 java.io.IOException)。該元素也包含帶有資源 URL 路徑的 <location> 元素，以便在發生錯誤時顯示。

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

注意：截至筆者撰稿時，您尚無法就部分錯誤狀況，設定自訂錯誤處理常式。更確切地說，URL 沒有定義的 servlet 對應時，您無法自訂 404 回應代碼，也無法自訂 403 Quota 錯誤頁面或是因為「應用服務引擎」內部錯誤而導致的 500 伺服器錯誤。

尚未支援的 web.xml 功能

「應用服務引擎」支援使用 <load-on-startup> 元素宣告 servlet。不過，載入必須等到網頁伺服器實例處理第一個要求期間 (而非之前)，才會實際發生。

「應用服務引擎」支援使用 <mime-mapping> 元素，為檔名結尾為特定副檔名的資源指定要使用的 MIME 類型。不過，MIME 對應只能套用至 servlet，無法套用至靜態檔案。靜態檔案採用一個固定的副檔名和 MIME 類型對應清單。

部分部署描述元的元素可以接受人類可讀的顯示名稱、描述和圖示，以便在 IDE 中使用。「應用服務引擎」不僅不使用這些元素，還會忽略它們。

「應用服務引擎」不支援 JNDI 環境變數 (<env-entry>)。

「應用服務引擎」不支援 EJB 資源 (<resource-ref>)。

<distributable> 元素會被忽略。

不支援使用 <run-at> 的 servlet 排程。