設定 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 標準,請參閱 Metawerx 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 的類別,以及初始化參數。您可以使用擁有不同初始化參數的相同類別,宣告多個 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>

在這個範例中,對網址 http://www.example.com/blue/teamProfile 的要求由 TeamServlet 類別處理,且 teamColor 參數等於 bluebgColor 參數等於 #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>

注意事項:如果 JSP 位於應用程式的根目錄中,則 <jsp-file> 的開頭必須為正斜線 (/)。

您可以使用 <taglib> 元素安裝 JSP 標記程式庫。標記程式庫中包含 JSP 標記程式庫描述元 (TLD) 檔案的路徑 (<taglib-location>),以及 JSP 用來選取要載入的程式庫的 URI (<taglib-uri>)。請注意,App Engine 會提供 JavaServer Page 標準標記程式庫 (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.jsphelp/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-name> 元素來比對所宣告 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>

注意事項:即使路徑符合 filter-mapping 模式,系統也不會在靜態資產中叫用篩選器。靜態檔案會直接提供給瀏覽器。

錯誤處理常式

您可以使用部署作業描述元,自訂伺服器在發生錯誤時要傳送給使用者的訊息。伺服器在即將傳送特定的 HTTP 狀態碼時,或在 Servlet 引發特定的 Java 例外狀況時,可以顯示替代頁面位置。

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

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

附註:目前您尚無法就部分錯誤狀況,設定自訂錯誤處理常式。更確切地說,網址沒有定義的 Servlet 對應時,您無法自訂 404 回應頁面,也無法自訂 403 配額錯誤頁面或是因為 App Engine 內部錯誤而導致的 500 伺服器錯誤頁面。

尚未支援的 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 排程。
  • 系統不支援安全性限制:如要瞭解對等功能,請參閱 Bookshelf 教學課程
  • web.xml 不支援「機密性」。
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 適用的 App Engine 彈性環境文件