返回介绍
文江博客 开发文档 Spring MVC 学习指南 第二版 文章详情

E.1 概述

发布于 2025-04-22 20:10:08 字数 17140 浏览 0 评论 0 收藏

在 Servlet 3 之前，部署工作必然涉及部署描述符，即 web.xml 文件，我们在该文件中配置应用程序的各个方面。但在 Servlet 3 中，部署描述符是可选的，因为我们可以使用标注来映射一个 URL 模式的资源。不过，若存在如下场景，则依然需要部署描述符。

  • 需要传递初始参数给 ServletContext。

  • 有多个过滤器，并要指定调用顺序。

  • 需要更改会话超时设置。

  • 要限制资源的访问，并配置用户身份验证方式。

清单 E.1 展示了部署描述符的框架。它必须被命名为 web.xml 且合并在应用目录的 WEB-INF 目录下。

清单 E.1 部署描述符的框架

< ?xml version="1.0" encoding="ISO-8859-1"?>
< web-app version="3.1" 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"
   [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 设置。

每个元素的配置规则可见 web-app_3_1.xsd 文档，可以从如下网站下载：

http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd

web-app_3_1.xsd 包括另一种模式（webcommon_3_1.xsd），其中包含了大部分信息。可从如下网站下载：

http://xmlns.jcp.org/xml/ns/javaee/web-common_3_1.xsd

webcommon_3_1.xsd 包括以下两种模式：

  • javaee_7.xsd，定义了其他 Java 共享公共元素 EE7 的部署类型（EAR、JAR 和 RAR）。

  • jsp_2_7.xsd，定义要素配置的一部分，JSP 根据 JSP 2.3 规范中的应用。

本节列出了在部署描述符中常见的 Servlet 和 jsp 元素，但不包括那些不在 Servlet 或 JSP 规范中的 Java EE 元素。

E.1.1 核心元素

本节将详细介绍各重要元素的细节。web-app 的子元素可以以任何顺序出现。某些元素，如 session-config、jsp-config 和 login-config 只能出现一次，而另一些元素，如 Servlet、filter 和 welcome-file-list 可以出现很多次。

后续几个小节会分别描述在<web-app>元素下的一级元素。若要查找非<web-app>下的非一级元素，请查找其父元素。例如，taglib 元素在“jsp-config”下，而 load-on-startup 在 Servlet 下。本节后续小节按字母顺序排序。

E.1.2 context-param

可用 context-param 元素传值给 ServletContext。这些值可以被任何 Servlet/JSP 页面读取。context-param 元素由名称/值对构成，并可以通过调用 ServletContext 的 getInitParameter 方法来读取。可以定义多个 context-param 元素，每个参数名在本应用中必须唯一。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>

E.1.3 distributable

若定义了 distributable 元素，则表明应用程序已部署到分布式的 Servlet/JSP 容器。distributable 元素必须是空的。例如，下面是一个 distributable 例子。

<distributable/>

E.1.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>

E.1.5 filter

filter 指定一个 Servlet 过滤器。该元素至少包括一个 filter-name 元素和一个 filter-class 元素。此外，它也可以包含以下元素：icon、display-name、discription、init-param 以及 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>

E.1.6 filter-mapping

过滤器映射元素是指定过滤器要被映射到的一个或多个资源。过滤器可以被映射到 Servlet 或者 URL 模式。将过滤器映射到 Servlet 会致使过滤器对该 Servlet 产生作用。将过滤器映射到 URL 模式，则会使其对所有 URL 与该 URL 模式匹配的资源进行过滤。过滤的顺序与过滤器映射元素在部署描述符中的顺序一致。

过滤器映射元索中包含一个 filter-name 元素和一个 url-pattern 元素或者 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>

E.1.7 listener

listener 元素用来注册一个侦听器。其子元素 listener-class 包含监听器类的全路径名。如下是一个示例：

<listener>
  <listener-class>com.example.AppListener</listener-class>
</listener>

E.1.8 locale-encoding-mapping-list 和 locale-encoding-mapping

locale-encoding-mapping-list 元素包含了一个或多个 locale-encoding-mapping 元素。每个 locale-encoding-mapping 定义了 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>

E.1.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 认证方式，则该元素被忽略。

form-login-config 元素包括 form-login-page 和 form-error-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>

E.1.10 mime-mapping

mime-mapping 元素用来把一个 MIME 类型映射到一个扩展名。该元素由一个 extension 元素和一个 mime-type 元素组成。示例如下：

<mime-mapping>
  <extension>txt</extension>
  <mime-type>text/plain</mime-type>
</mime-mapping>

E.1.11 security-constraint

security-constraint 元素允许对一组资源进行限制访问。

security-constraint 元素有如下子元素：一个可选的 display-name 元素、一个或多个 web-resource-collection 元素、可选的 auth-constraint 元素和一个可选的 user-data-constraint 元素。

web-resource-collection 元素标识了一组需要进行限制访问的资源集合。这里，你可以定义 URL 模式和所限制的 HTTP 方法。如果没有定义 HTTP 方法，则表示应用于所有 HTTP 方法。

auth-constraint 元素指明哪些角色可以访问受限制的资源集合。如果没有指定，则应用于所有角色。

user-data-constraint 元素用于指示在客户端和 Servlet/JSP 容器传输的数据是否保护。

web-resource-collection 元素包含一个 web-resource-name 元素、一个可选的 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>

E.1.12 security-role

security-role 元素声明用于安全限制的安全角色。这个元素有一个可选的 description 元素和 role-name 元素。下面是一个例子：

<security-role>
  <role-name>payingMember</role-name>
</security-role>

E.1.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-on-startup 元素，则值小的 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-class>
  <load-on-startup>10</load-on-startup>
</servlet>
<servlet>
  <servlet-name>SecureServlet</servlet-name>
  <servlet-class>com.brainysoftware.SecureServlet</servlet-class>
  <load-on-startup>20</load-on-startup>
</servlet>

E.1.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>

E.1.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>

E.1.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>

E.1.17 JSP-Specific Elements

<web-app>元素下的 jsp-config 元素，可以指定 JSP 配置。它可以具有零个或多个标签 taglib 和零个或多个 jsp-property-group 元素。下面首先介绍 taglib 元素，然后介绍 jsp-property-group 元素。

E.1.18 taglib

taglib 元素定义了 JSP 定制标签库。taglib 元素包含一个 taglib-uri 元素和 taglib-location 元素。taglib-uri 元素定义了 Servlet/JSP 应用程序所用的标签库的 URI，其值相当于在部署描述符路径。

taglib-location 元素指定 TLD 文件的位置。

下面是一个 taglib 元素的例子。

<jsp-config>
  <taglib>
    <taglib-uri>
      http://brainysoftware.com/taglib/complex
    </taglib-uri>
    <taglib-location>/WEB-INF/jsp/complex.tld
  </taglib-location>
 </taglib>
</jsp-config>

E.1.19 jsp-property-group

jsp-property-group 中的元素可为一组 JSP 文件统一配置属性。使用<jsp-property-group>子元素可做到以下几点：

  • 指示 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 页面的编码。page-encoding 的有效值和页面的 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>

发布评论

需要 登录 才能够评论， 你可以免费 注册 一个本站的账号。
列表为空，暂无数据
    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站，即表示您同意使用 Cookies 和您的相关数据。