部署一个Servlet 3.0应用程序是一件轻而易举的 事。通过Servlet注解类型，对于不太复杂的应用程序， 可以部署没有描述符的Servlet/JSP应用程序。尽管如 此，在需要更加精细配置的情况下，部署描述符仍然需 要。首先，部署描述符必须被命名为web.xml并且位于 WEB-INF目录下，Java类必须放置在WEB-INF/classes 目录下，而Java类库则必须位于WEB-INF/lib目录下。 所有的应用程序资源必须打包成一个以.war为后缀的 JAR文件。
一. 概述
在Servlet 3.0之前，部署工作必然涉及部署描述 符，即web.xml文件，我们在该文件中配置应用程序的 各个方面。但在Servlet 3.0中，部署描述符是可选的， 因为我们可以使用标注来映射一个URL模式的资源。不 过，若存在如下场景，则依然需要部署描述符：
- 需要传递初始参数给ServletContext。
- 有多个过滤器，并要指定调用顺序。
- 需要更改会话超时设置。
- 要限制资源的访问，并配置用户身份验证方式。
下面展示了部署描述符的框架。它必须被命名 为web.xml且合并在应用目录的WEB-INF目录下。
<?xml version="1.0" encoding="ISO-8859-1"?> <web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee ➥ http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="4.0" [metadata-complete="true|false"] > ... </web-app>
xsi:schemaLocation属性指定了模式文档的位置，以 便可以进行验证。version属性指定了Servlet规范的版 本。
可选的metadata-complete属性指定部署描述符是否 是完整的，若值为True，则Servlet/JSP容器将忽略 Servlet注解。若值为False或不存在，则容器必须检查类 文件的Servlet注解，并扫描web fragments文件。
web-app元素是文档的根元素，并且可以具有如下 子元素：
- Servlet声明
- Servlet映射
- ServletContext的初始化参数
- 会话配置
- 监听器类
- 过滤器定义和映射
- MIME类型映射
- 欢迎文件列表
- 错误页面
- JSP特定的设置
- JNDI设置
每个元素的配置规则可见app_4_0.xsd文档，可以 从如下网站下载：
http://java.sun.com/xml/ns/javaee/web-app_4_0.xsd
url-pattern元素用来指定可应用相应属性配置的 URL模式。
app_4_0.xsd包括另一种模式 （webcommon_4_0.xsd），其中包含了大部分信息。可 从如下网站下载：
https://www.oracle.com/webfolder/technetwork/jsc/xml/ns/javaee/web-common_4_0.xsd
webcommon_3_0.xsd包括以下两种模式：
- javaee_7.xsd，定义了其他Java共享公共元素EE7的 部署类型（EAR、JAR和RAR）。
- jsp_2_3.xsd，根据JSP 2.3规范，通过配置应用程序 的JSP部分来定义元素。
1. 核心元素
web-app的子 元素可以以任何顺序出现。某些元素，如sessionconfig、jsp-config和login-config只能出现一次，而另一 些，如Servlet、filter和welcome-file-list可以出现很多 次。
2. context-param
可用context-param元素传值给ServletContext。这些 值可以被任何Servlet/JSP页面读取。context-param元素 由名称/值对构成，并可以通过调用ServletContext的 getInitParameter方法来读取。可以定义多个 contextparam 元素，每个参数名在本应用中必须唯一。 ServletContext. getInitParameterNames()方法会返回所有 的参数名称。
每个context-param元素必须包含一个param-name元 素和一个param-value元素。param-name定义参数名，而 param-value定义参数值。另有一个可选的元素，即 description元素，用来描述参数。
下面是context-param元素的两个例子：
<context-param> <param-name>location</param-name> <param-value>localhost</param-value> </context-param> <context-param> <param-name>port</param-name> <param-value>8080</param-value> <description>The port number used</description> </context-param>
3. distributable
若定义了distributable元素，则表明应用程序已部署 到分布式的Servlet/JSP容器。distributable元素必须是空 的。例如，下面是一个distributable例子：
<distributable/>
4. error-page
error-page元素包含一个HTTP错误代码与资源路径 或Java异常类型与资源路径之间的映射关系。error-page 元素定义容器在特定HTTP错误或异常时应返回的资源 路径。
Error-page元素由如下成分构成：
- error-code，指定一个HTTP错误代码
- exception-type，指定Java的异常类型（全路径名 称）。
- location，指定要被显示的资源位置。该元素必须 以“/”开始。
下面的配置告诉Servlet/JSP容器，当出现HTTP 404 时，显示位于应用目录下的error.html页面。
<error-page> <error-code>404</error-code> <location>/error.html</location> </error-page>
下面的配置告诉Servlet/JSP容器，当发生 ServletException时，显示exception.html页面。
<error-page> <exception-type>javax.servlet.ServletException</exception-type> <location>/exception.html</location> </error-page>
5. filter
filter指定一个Servlet过滤器。该元素至少包括一个 filter-name元素和一个filter-class元素。此外，它也可以 包含以下元素：icon、display-name、discription、initparam以及async-supported。
filter-name元素定义了过滤器的名称。过滤器名称 必须全局唯一。filter-class元素指定过滤器类的全路径 名称。可由init-param元素来配置过滤器的初始参数 （类似于<context-param>），一个过滤器可以有多个 init-param。
下面是Upper Case Filter和Image Filter两个filter元 素。
<filter> <filter-name>Upper Case Filter</filter-name> <filter-class>com.example.UpperCaseFilter</filter-class> </filter> <filter> <filter-name>Image Filter</filter-name> <filter-class>com.example.ImageFilter</filter-class> <init-param> <param-name>frequency</param-name> <param-value>1909</param-value> </init-param> <init-param> <param-name>resolution</param-name> <param-value>1024</param-value> </init-param> </filter>
6.filter-mapping
过滤器映射元素是指定过滤器要被映射到的一个或 多个资源。过滤器可以被映射到servlet或者URL模式。 将过滤器映射到servlet会致使过滤器对该servlet产生作 用。将过滤器映射到URL模式，则会使其对所有URL与 该URL模式匹配的资源进行过滤。过滤的顺序与过滤器 映射元素在部署描述符中的顺序一致。
过滤器映射元素中包含一个filter-name元素和一个 URL模式元素或者servlet-name元素。
filter-name元素的值必须与利用filter元素声明的某 一个过滤器名称相匹配。
下面的例子中是两个过滤器元素和两个过滤器映射 元素。
<filter> <filter-name>Logging Filter</filter-name> <filter-class>com.example.LoggingFilter</filter-class> </filter> <filter> <filter-name>Security Filter</filter-name> <filter-class>com.example.SecurityFilter</filter-class> </filter> <filter-mapping> <filter-name>Logging Filter</filter-name> <servlet-name>FirstServlet</servlet-name> </filter-mapping> <filter-mapping> <filter-name>Security Filter</filter-name> <url-pattern>/ *</url-pattern> </filter-mapping>
7. listener
listener元素用来注册一个侦听器，其子元素 listener-class包含监听器类的全路径名。如下是一个示 例：
<listener> <listener-class>com.example.AppListener</listener-class> </listener>
8. locale-encoding-mapping-list和 locale-encoding-mapping
locale-encoding-mapping-list元素包含了一个或多个 locale-encoding-mapping元素。每个locale-encodingmapping定义了locale以及编码的映射，分别用locale以 及encoding元素定义。locale元素的值必须是定义在ISO 639中的语言编码，如en，或者是采用“语言编码_国家 编码”格式，如en_US。其中，国家编码值必须定义在 ISO 3166中。
如下是一个示例：
<locale-encoding-mapping-list> <locale-encoding-mapping> <locale>ja</locale> <encoding>Shift_JIS</encoding> </locale-encoding-mapping> </locale-encoding-mapping-list>
9. login-config
login-config元素包括auth-method、realm-name以及 form-login-config元素，每个元素都是可选的。
auth-method元素定义了认证方式，可选值为 BASIC、DIGEST、FORM、CLIENT-CERT
realm-name元素定义了用于BASIC以及DIGEST认 证方式的realm名称。
form-login-config则定义了用于FORM认证方式的 登录页面和失败页面。若没有采用FORM认证方式，则 该元素被忽略。
orm-login-config元素包括form-login-page和formerror-page两个子元素。其中，form- login-page配置了显 示登录页面的资源路径，路径为应用目录的相对路径， 且必须以“/”开始；form-error-page则配置了登录失败时
显示错误页面的资源路径，同样，路径为应用目录的相 对路径，且必须以“/”开始。
下面是一个示例
<login-config> <auth-method>DIGEST</auth-method> <realm-name>Members Only</realm-name> </login-config>
另一个示例如下：
<login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/loginForm.jsp</form-login-page> <form-error-page>/errorPage.jsp</form-error-page> </form-login-config> </login-config>
10. mime-mapping
mime-mapping元素用来映射一个MIME类型到一个 扩展名，它由一个extension元素和一个mime-type元素 组成。示例如下：
<mime-mapping> <extension>txt</extension> <mime-type>text/plain</mime-type> </mime-mapping>
11. security-constraint
security-constraint元素允许对一组资源进行限制访 问。
security-constraint元素有如下子元素：一个可选的 display-name元素、一个或多个web- resource-collection 元素、可选的auth-constraint元素和一个可选的user-dataconstraint元素。
web-resource-collection 元素标识了一组需要进行限 制访问的资源集合。这里，你可以定义URL模式和所限 制的HTTP方法。如果没有定义HTTP方法，则表示应用 于所有HTTP方法。
auth-constraint元素指明哪些角色可以访问受限制的 资源集合。如果没有指定，则应用于所有角色。
user-data-constraint元素用于指示在客户端和 Servlet/JSP容器传输的数据是否保护。
web-resource-collection元素包含一个web-resourcename元素、一个可选的description元素、零个或多个 url-pattern元素，以及零个或多个http-method元素。
web-resource-name元素指定受保护的资源名称。
http-method元素指定HTTP方法，如GET、POST或 TRACE。
auth-constraint元素包含一个可选的description元 素、零个或多个role-name元素。role-name元素指定角 色名称。
user-data-constraint元素包含一个可选的description 元素和一个transport-guarantee元素。transport-guarantee 元素的取值范围有：NONE、INTEGRAL或 CONFIDENTIAL。NONE表示该应用程序不需要安全 传输保障。INTEGRAL意味着服务器和客户端之间的数 据在传输过程中不能被篡改。CONFIDENTIAL意味着 必须加密传输数据。大多数情况下，安全套接字层 （SSL）会被应用于INTEGRAL或CONFIDENTIAL。
下面是一个例子：
<security-constraint> <web-resource-collection> <web-resource-name>Members Only</web-resource-name> <url-pattern>/members/ *</url-pattern> </web-resource-collection> <auth-constraint> <role-name>payingMember</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>Digest</auth-method> <realm-name>Digest Access Authentication</realm-name> </login-config>
12. security-role
security-role元素声明用于安全限制的安全角色。 这个元素有一个可选的description元素和role-name元素。下面是一个例子：
<security-role> <role-name>payingMember</role-name> </security-role>
13. Servlet
Servlet元素用来配置Servlet，包括如下子元素：
- 一个可选的icon元素
- 一个可选的description元素
- 可选的display-name元素
- 一个servlet-name元素
- 一个servlet-class元素或一个jsp-file元素
- 零个或更多的init-param元素
- 一个可选的load-on-startup元素
- 可选的run-as元素
- 可选的enabled元素
- 可选的async-supported元素
- 可选的multipart-config元素
- 零个或多个security-role-ref元素
一个Servlet元素至少必须包含一个servlet-name元素 和一个servlet-class元素，或者一个servlet-name元素和 一个jsp-file元素。
servlet-name元素定义的Servlet名称必须在应用程序 中是唯一的。
servlet-class元素指定的类名为全路径名。
jsp-file元素指定JSP页面的路径，该路径是应用程 序的相对路径，必须以“/”开始。
init-param的子元素可以用来传递一个初始参数给 Servlet。init-param元素的构成同context-param。
可以使用load-on-startup元素在Servlet/JSP容器启动 时自动加载Servlet。加载一个Servlet是指实例化Servlet 和调用它的init方法。使用此元素可以避免由于加载 Servlet而导致对第一个请求的响应延迟。如果该元素指 定了jsp-file元素，则JSP文件被预编译成Servlet，并加 载该Servlet。
load-on-startup可以指定用一个整数值来指定加载 顺序。例如，如果有两个Servlet且都包含一个load-onstartup元素，则值小的Servlet优先加载。若没有指定值 或值为负数，则由Web容器决定如何加载。若两个 Servlet具有相同的load-on-startup值，则加载Servlet的顺 序不能确定。
run-as用来覆盖调用EJB的安全标识。角色名是当 前Web应用程序定义的安全角色之一。
security-role-ref元素映射在调用Servlet的 isUserInRole方法时角色名到应用程序定义的安全角 色。security-role-ref元素包含一个可选的description元 素、一个role-name元素和一个role-link元素。
role-link元素用于安全角色映射到一个已定义的安 全角色，必须包含一个定义在security-role元素中的安 全角色。
async-supported元素是一个可选的元素，其值可以 是True或False。它表示Servlet是否支持异步处理。
enabled元素也是一个可选的元素，它的值可以是 True或False。设置此元素为False，则禁用这个Servlet。
例如，映射安全角色“PM”与角色名 字“payingMember”的配置如下：
<security-role-ref> <role-name>PM</role-name> <role-link>payingMember</role-link> </security-role-ref>
这样，若属于payingMember角色的用户调用Servlet 的isUserInRole（“payingMember”）方法，则结果为 真。
下面是Servlet元素的两个例子：
<servlet> <servlet-name>UploadServlet</servlet-name> <servlet-class>com.brainysoftware.UploadServlet</servlet-cl ass> <load-on-startup>10</load-on-startup> </servlet> <servlet> <servlet-name>SecureServlet</servlet-name> <servlet-class>com.brainysoftware.SecureServlet</servlet-cl ass> <load-on-startup>20</load-on-startup> </servlet>
14. servlet-mapping
servlet-mapping元素映射一个Servlet到一个URL模 式。该元素必须有一个servlet-name元素和url-pattern元 素。
下面的servlet-mapping元素映射一个Servlet 到/first：
<servlet> <servlet-name>FirstServlet</servlet-name> <servlet-class>com.brainysoftware.FirstServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>FirstServlet</servlet-name> <url-pattern>/first</url-pattern> </servlet-mapping>
15. session-config
session-config元素定义了用于 javax.servlet.http.HttpSession实例的参数。此元素可包含 一个或更多的以下内容：session-timeout、cookie-config 或tracking-mode。
session-timeout元素指定会话超时间隔（分钟）。 该值必须是整数。如果该值是零或负数，则会话将永不 超时。
cookie-config元素定义了跟踪会话创建的cookie的 配置。
tracking-mode元素定义了跟踪会话模式，其有效值 是COOKIE、URL或SSL。
下面定义的session-config元素使得应用的 HttpSession对象在不活动12分钟后失效：
<session-config> <session-timeout>12</session-timeout> </session-config>
16. welcome-file-list
welcome-file-list元素指定当用户在浏览器中输入的 URL不包含一个Servlet名称或JSP页面或静态资源时显 示的文件或Servlet。
welcome-file-list元素包含一个或多个welcome-file 元素。welcome-file元素包含默认的文件名。如果在第 一个welcome-file元素中指定的文件没有找到，则在 Web容器将尝试显示第二个，直到最后一个。
下面是一个welcome-file-list元素的例子：
<welcome-file-list> <welcome-file>index.htm</welcome-file> <welcome-file>index.html</welcome-file> <welcome-file>index.jsp</welcome-file> </welcome-file-list>
下面的示例，第一个welcome-file元素指定了一个 在应用程序目录下的index.html；第二个welcome-file为 Servlet目录下的欢迎文件：
<welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>servlet/welcome</welcome-file> </welcome-file-list>
17. JSP-Specific Elements
元素下的jsp-config元素，可以指定JSP 配置。它可以具有零个或多个taglib元素和零个或多个 jsp-property-group元素。下面首先介绍taglib元素，然后 介绍jsp-property-group元素。
18. taglib
taglib元素定义了JSP定制标签库。taglib元素包含 一个taglib-uri元素和taglib-location元素。taglib-uri元素 定义了Servlet/JSP应用程序所用的标签库的URI，其值 相当于部署描述符路径。
taglib-location元素指定TLD文件的位置。
下面是一个taglib元素的例子：
<jsp-config> <taglib> <!-- taglib-uri 指定了taglib元素的路径 --> <taglib-uri>http://brainysoftware.com/taglib/complex</taglib-uri> <!-- taglib-location元素指定TLD文件的位置 --> <taglib-location>/WEB-INF/jsp/complex.tld</taglib-location> </taglib> </jsp-config>
19. jsp-property-group
jsp-property-group中的元素可为一组JSP文件统一 配置属性。使用子元素可做到以下 几点：
- 指示EL显示是否忽略；
- 指示脚本元素是否允许；
- 指明页面的编码信息；
- 指示一个资源是JSP文件（XML编写）；
- 预包括和代码自动包含。
jsp-property-group包含如下子元素：
- 一个可选的description元素
- 一个可选的display-name元素
- 一个可选的icon元素
- 一个或多个url-pattern元件
- 一个可选的el-ignored元素
- 一个可选的page-encoding元素
- 一个可选的scripting-invalid元素
- 一个可选的is-xml元素
- 零个或多个include-prelude元素
- 零个或多个include-code元素
url-pattern元素用来指定可应用相应属性配置的 URL模式。
el-ignored元素值为True或False。True值表示匹配 URL模式的jsp页面中，EL表达式无法被计算，该元素 的默认值是False。
page-encoding元素指定JSP页面的编码。pageencoding的有效值同页面的pageEncoding有效值。若 page-encoding指定值与匹配URL模式的JSP页面中的 pageEncoding属性值不同，则会产生一个转换时间错 误。同样，若page-encoding指定值与XML文档申明的 编码不同，也会产生一个转换时间错误。
scripting-invalid元素值为True或False。True值是指 匹配URL模式的JSP页面不支持<% scripting %>语法。 scripting-invalid元素的默认值是False。
is-xml元素值为True或False，True表示匹配URL模 式的页面是JSP文件。
include-prelude元素值为相对于Servlet/JSP应用的相对路径。若设定该元素，则匹配URL模式的JSP页面开头处会自动包含给定路径文件（同include指令）。
include-coda元素值为相对于Servlet/JSP应用的相对 路径。若设定该元素，则匹配URL模式的JSP页面结尾 处会自动包含给定路径文件（同include指令）。
下面的例子中，jsp-property-group配置所有的JSP 页面无法执行EL表达式：
<jsp-config> <jsp-property-group> <url-pattern>*.jsp</url-pattern> <el-ignored>true</el-ignored> </jsp-property-group> </jsp-config>
下面的例子中，jsp-property-group配置所有的JSP 页面不支持<% scripting %>语法
<jsp-config> <jsp-property-group> <url-pattern>*.jsp</url-pattern> <scripting-invalid>true</scripting-invalid> </jsp-property-group> </jsp-config>
二. 部署
从Servlet 1.0开始，可以很方便地部署一个 Servlet/JSP应用程序。仅需要将应用原始目录结构压缩 成一个WAR文件。可以在JDK中使用jar工具或流行的 工具，如WinZip。需要确保压缩文件有.war扩展名。如 果使用WinZip，则在压缩完成后重命名文件。
WAR文件必须包含所有库文件、类文件、HTML 文件、JSP页面、图像文件以及版权声明（如果有的 话）等，但不包括Java源文件。任何人都可以获取一个 WAR文件的副本，并部署到一个Servlet/JSP容器上。
三. web fragment
Servlet 3添加了web fragment特性，用来为已有的 Web应用部署插件或框架。web fragment被设计成部署 描述符的补充，而无须编辑web.xml文件。一个web fragment基本上包含了常用的Web对象，如Servlet、过 滤器和监听器，其他资源如JSP页面和静态图像的包文 件（JAR文件）。一个web fragment也可以有一个描述 符，类似的部署描述符的XML文档。web fragment描述 符必须命名为web-fragment.xml，并位于包的METAINF目录下。一个web fragment描述可能包含任意可出 现在部署描述符web-app元素下的所有元素，再加上一 些web fragment的特定元素。一个应用程序可以有多个 Web片段。
清单显示了web fragment描述，以黑体形式突 出显示与部署描述符之间的不同内容。在web fragment 的根元素必须是web-fragment元素，其可以有metadatacomplete属性。如果metadata-complete属性的值为 True，则包含在web fragment中所有的类注释将被跳 过。
<?xml version="1.0" encoding="ISO-8859-1"?> <web-fragment xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee ➥ http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd" version="3.0" [metadata-complete="true|false"] > ... </web-fragment>
作为一个例子，在app13a应用程序中包含的 fragment.jar文件是一个web fragment。该JAR文件已经 导入到WEB-INF/lib目录下。本实例的重点不在于 app13a，而是web fragment项目。该项目包含一个 Servlet（FragmentServlet）和 webfragment.xml文。
FragmentServlet类
package fragment.servlet; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; public class FragmentServlet extends HttpServlet { private static final long serialVersionUID = 940L; public void doGet(HttpServletRequest request, HttpServletRe sponse response) throws ServletException, IOException { response.setContentType("text/html"); PrintWriter out = response.getWriter(); out.println("A plug-in"); } }
webfragment.xml文件
<?xml version="1.0" encoding="ISO-8859-1"?> <web-fragment xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee ➥ http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd" version="3.0"> <servlet> <servlet-name>FragmentServlet</servlet-name> <servlet-class>servlet.FragmentServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>FragmentServlet</servlet-name> <url-pattern>/fragment</url-pattern> </servlet-mapping> </web-fragment>
FragmentServlet是一个发送一个字符串到浏览器的 简单的Servlet。web-fragment.xml文件注册并映射该 Servlet。fragment.jar文件结构如图所示。
调用如下URL测试该Servlet：
http://localhost:8080/app13a/fragment