20200311 14. 部署描述文件

14. 部署描述文件 web.xml

本章指定的 Java™Servlet 规范 3.0 版要求 Web 容器支持部署描述文件。部署描述文件表达了应用开发人员、应用集成人员和 Web 应用部署人员之间的元素和配置信息。

对于 Java Servlet 2.4 和以后的版本，部署描述文件在 XML 模式文档中定义。

为了向后兼容到 2.2 版本的 API 编写的应用程序， Web 容器也需要支持 2.2 版本的部署描述文件。为了向后兼容 2.3 版本的 API 编写的应用程序， Web 容器也需要支持 2.3 版本的部署描述文件。 2.2 版本的部署描述文件可在此下载， 2.3 版本的部署描述文件可在此下载。

14.1 部署描述文件元素

所有 servlet 容器的 Web 应用程序部署描述文件需要支持以下类型的配置和部署信息：

• ServletContext 初始化参数
• Session 配置
• Servlet 声明
• Servlet 映射
• 应用程序生命周期监听器类
• 过滤器定义和过滤器映射
• MIME 类型映射
• 欢迎文件列表
• 错误页面
• 语言环境和编码映射
• 安全配置，包括 login-config， security-constraint， security-constraint， security-role-ref 和 run-as

14.2 部署描述符处理规则

本节列出了一些通用的规则， Web 容器和开发人员必须注意有关 Web 应用程序部署描述文件的处理。

• 对于部署描述文件的文本节点元素内容， Web 容器必须删除所有前导和后置空格，空格在 XML 1.0 中被定义为 “S(white space)”。

• 部署描述文件对模式来说必须是有效的。 Web 容器和操作 Web 应用程序的工具对检查 WAR 文件的有效性有多种选择。包括检查 WAR 文件中部署描述文件的有效性。

  此外，推荐 Web 容器和操作 Web 应用程序的工具提供一个级别的语义检查。例如，应该检查安全约束中引用的角色和部署描述文件中定义的某个安全角色具有相同的名称。

  在 Web 应用程序不符合规范的情况下，工具和容器应该用描述性的错误消息告知开发人员。鼓励高端应用服务器提供商都提供这种有效性检查，以工具的形式和容器分开。

• 这个版本的规范中， web-app 的子元素的顺序可以是任意的。由于 XML 模式的限制，可分发元素多样性，session-config、 welcome-file-list、 jsp-config、 login-config 以及 locale-encoding-mapping-list，从“可选的”变成“0 个或多个”。当部署描述文件包含多个 session-config、 jsp-config 和 login-config 时，容器必须用描述性的错误消息告知开发人员。当有多个事件时，容器必须连接 welcome-file-list 和 locale-encoding-mapping-list 中的项目。多个可分发的事件必须与单个可分发的事件以同样的方式正确对待。

• 假定部署描述符中指定的 URI 路径通过 URL 解码形式（意思是已经对 URL 进行了转义）。当 URL 包含CR(#xD)（回车）或 LF(#xA)（换行）时，容器必须用描述性的错误消息告知开发人员。容器必须保存所有其他字符，包括 URL 中的空格。

• 容器必须尝试规范化部署描文件中的路径。例如， /a/../b 形式的路径必须解释为/b。部署描述文件中以../ 始的路径或解析成以../开始的路径都不是有效的路径。

• URI 路径指的是相对于 WAR 文件的根目录，或相对于 WAR 文件的根目录的一个路径映射，除非另有规定，应以/开头。

• 元素的值是一个枚举类型，其值是区分大小写的。

14.3 部署描述文件

这个版本规范的部署描述文件可在此下载

14.4 部署描述文件图解

本节举例说明部署描述文件中的元素。属性没有在图中显示。详细信息请参阅部署描述文件模式。

1、 web-app 元素

web-app 元素是一个 Web 应用程序的根部署描述符。此元素包含下列元素。这个元素有一个必需的属性 version 来指定部署描述符符合哪个版本的模式。此元素的所有子元素可以是任意的顺序。

2、 description 元素

description 元素提供了父元素的文本描述。此元素不仅出现在 web-app 元素中，其他很多元素中也有。它有一个可选属性 xml:lang 指明描述中使用哪一种语言。该属性的默认值是英语（ “en”）。

3、 display-name 元素

display-name 元素包含一个简短的名称，目的是通过工具显示。显示名称不必是唯一的。这个元素有一个可选属性 xml:lang 用于指定语言。

4、 icon 元素

icon 元素包含 small-icon 和 large-icon 元素，为大型和小型 GIF 或 JPEG 图标图片指定文件名，用于在 GUI 工具中表示父元素。

5、 distributable 元素

distributable 元素表示设定该 Web 应用程序适合部署到一个分布式的 servlet 容器中。

6、 context-param 元素

context-param 元素包含了 Web 应用程序的 servlet 上下文初始化参数的声明。

7、 filter 元素

filter 元素声明了 Web 应用程序中的过滤器。该过滤器映射到一个 servlet 或 filter-mapping 元素中的一个 URL 模式，使用 filter-name 的值来引用。过滤器在运行时可以通过 FilterConfig 接口访问部署描述文件中声明的初始化参数。

filter-name 元素是过滤器的逻辑名称。它在 Web 应用程序中必须是唯一的。 filter-name 元素的元素内容不能为空。

filter-class 是过滤器的完全限定类名。

init-param 元素包含的名值对作为此过滤器的初始化参数。

当指定可选的 async-supported 元素时，表示该过滤器支持异步请求处理。

8、 filter-mapping 元素

容器使用 filter-mapping 决定哪个过滤器以什么样的顺序应用到请求。 filter-name 的值必须是部署描述文件中声明的过滤器中的一个。匹配的请求可以被指定为 url-pattern 或 servlet-name。

9、 listener 元素

listener 表示应用程序监听器 bean 的部署属性。

子元素 listener-class 声明应用程序中的一个类必须注册为 Web 应用程序监听器 bean。它的值是监听器类的完全限定类名。

10、 servlet 元素

servlet 元素用于声明一个 servlet。它包含一个 servlet 的声明性数据。

jsp-file 元素包含到以“/”开头的 Web 应用程序中一个 JSP 文件的完全路径。如果指定了 jsp-file 并且存在 load-on-start 元素，那么 JSP 应该被预编译和加载。

servlet-name 元素包含了 servlet 的规范名称。在 Web 应用程序中每个 servlet 的名称是唯一的。servlet-name 元素内容不能为空。

servlet-class 包含了 servlet 的完全限定类名。

run-as 元素指定用作一个组件执行的标识。它包含一个可选的 description，和一个由 role-name 元素指定安全角色。

load-on-startup 元素表示该 servlet 应该在 Web 应用程序启动时加载（实例化并调用它的 init()方法）。该元素的元素内容必须是一个整数，表示 servlet 应该被加载的顺序。如果该值是一个负整数，或不存在该元素，容器自由选择什么时候加载这个 servlet。如果该值是一个正整数或 0，当应用部署后容器必须加载和初始化这个 servlet。容器必须保证较小整数标记的 servlet 在较大整数标记的 servlet 之前加载。容器可以选择具有相同 load-on-startup 值的 servlet 的加载顺序。

security-role-ref 元素声明组件中或部署组件的代码中的安全角色引用。它由一个可选的 description，在代码中使用的安全角色名称（ role-name），以及一个可选的到一个安全角色（role-link）的 链 接 组 成 。 如 果 没 有 指 定 安 全 角 色 ， 部 署 器 必 须 选 择 一 个 合 适 的 安 全 角 色 。

当 指 定 了 可 选 的 async-supported 元素，指示的 servlet 可以支持异步请求处理。如果一个 servlet 支持文件上传功能和 mime-multipart 请求处理，通过描述文件中的 multipart-config 元素能够提供相同的配置。

multipart-config 元素可用于指定文件存储的位置，上传文件大小的最大值，最大请求大小和文件将写入磁盘之后的大小阈值。

11、 servlet-mapping 元素

servlet-mapping 定义了 servlet 和 URL 模式之间的映射

12、 session-config 元素

session-config 元素定义了该 Web 应用程序的会话参数。

子元素 session-timeout 定义了该 Web 应用程序中创建的所有会话的默认超时时间间隔。指定的超时时间必须使用分钟数表示。如果超时时间小于或等于 0，容器将确保会话的默认行为永远不会超时。如果没有指定这个元素，容器必须设置它的缺省超时期限。

13、 mime-mapping 元素

mime-mapping 定义了扩展名和 MIME 类型之间的映射。

extension 元素包含一个字符串描述的扩展名，例如“txt”。

14、 welcome-file-list 元素

welcome-file-list 包含了一个有序的欢迎文件列表。

子元素 welcome-file 包含一个用作缺省欢迎文件的文件名，如 index.html

15、 error-page 元素

error-page 包含一个错误代码或异常类型到 Web 应用程序中资源的路径之间的映射。

不过， error-code 或 exception-type 元素可以省略来指定一个默认的错误页面。

子元素 exception-type 包含了一个 Java 异常类型的完全限定名称。

子元素 location 包含了 web 应用程序中相对于 web 应用程序根目录的资源位置。 location 的值必须以'/'开头。

16、 jsp-config 元素

jsp-config 用 来 提 供 Web 应 用 程 序 中 的 JSP 文 件 的 全 局 配 置 信 息 。 它 有 两 个 子 元 素 ， taglib 和 jsp-property-group。

taglib 元素可用来为 Web 应用程序中的 JSP 页面使用的标签库提供信息。详细信息请参阅 JavaServer Pages 规范 2.1 版本。

17、 security-constraint 元素

security-constraint 用于关联安全约束和一个或多个 Web 资源集合。

子元素 web-resource-collection 确定安全约束应用到哪一些 Web 应用程序中资源的子集和这些资源的 HTTP 方法。

auth-constraint 表示用户角色应该允许访问此资源集合。这里使用的 role-name 必须与该 Web 应用程序定义的其中一个 security-role 元素的 role-name 对应，或者是指定的保留 role-name“*”对应，这是一个表示 web 应用程序中的所有角色的紧凑语法。如果“*”和角色名都出现了，容器会将此解释为所有角色。如果没有定义角色，不允许任何用户访问由包含 security-constraint 所描述的 Web 应用程序的部分。当容器确定访问时匹配角色名称是区分大小写的。

user-data-constraint 表示客户端和容器之间的通信数据如何受到子元素 transport-guarantee 的保护。transport-guarantee 的合法值是 NONE， INTEGRAL 或 CONFIDENTIAL 之一。

18、 login-config 元素

login-config 用于配置应该使用的验证方法，可用于此应用程序的领域名，以及表单登录机制所需要的属性。子元素 auth-method 为 Web 应用程序配置验证机制。该元素的内容必须是 BASIC、 DIGEST、 FORM、CLIENT-CERT、或 vendor-specific 验证模式。

realm-name 表示为 Web 应用程序选择用于验证模式的领域名。

form-login-config 指定应该用于基于表单登录的登录和错误页面。如果不使用基于表单的登录方式，这些元素将被忽略。

19、 security-role 元素

security-role 定义了一个安全角色。子元素 role-name 指定安全角色的名称。该名称必须符合 NMTOKEN 的词法规则。

20、 env-entry 元素

env-entry 声明了一个应用程序的环境入口。

子元素 env-entry-name 包含部署组件环境入口的名称。这个名称是一个相对于 java:comp/env 上下文的 JNDI 名称。在部署组件中该名称必须是唯一的。

env-entry-type 包含了应用程序代码所期望的环境入口值的 Java 类型完全限定名。

子元素 env-entry-value 指定部署组件的环境入口值。该值必须是一个 String，对指定的使用一个 String 或 java.lang.Character 类型作为参数的构造器有效。

可选的 injection-target 元素用来定义把指定的资源注入到字段或 JavaBean 属性。 injection-target 指定了 类 中 应 该 被 注 入 资 源 的 类 和 名 称 。

injection-target-class 指 定 了 注 入 目 标 的 完 全 限 定 类 名 称 。

injection-target-name 指定了指定类中的目标。首先把查找目标作为一个 JavaBean 属性名称。如果没有找到，则把查找目标作为一个字段名。在类初始化期间通过调用目标属性的 set 方法或给名称字段设置一个值将指定的资源注入到目标。如果环境入口指定了一个 injection-target，那么 env-entry-type 可以省略或必须与注入目标的类型匹配。如果没有指定 injection-target，那么需要指定 env-entry-type。

21、 ejb-ref 元素

ejb-ref 声明了一个对企业 bean 的 home 引用。

ejb-ref-name 指定了引用企业 bean 的部署组件代码中使用的名称。

ejb-ref-type 是引用的企业 bean 期望的类型，它可以是 Entity 或 Session。

home 定义了引用的企业 bean 的 home 接口的完全限定名称。

remote 定义了引用的企业 bean 的 remote 接口的完全限定名称。

ejb-link 指定了连接到企业 bean 的一个 EJB 引用。更多详细信息请参阅 Java 平台企业版第 6 版。

除了这些元素之外，injection-target 元素可以用于定义指定的企业 bean 注入到一个组件的字段或属性。

22、 ejb-local-ref 元素

ejb-local-ref 声明了对企业 bean 的本地 home 引用。

local-home 定义了企业 bean 的本地 home 接口的完全限定名称。

local 定义了企业 bean 的本地接口的完全限定名称。

23、 service-ref 元素

service-ref 声明了一个对 Web service 的引用。

service-ref-name 声明了用于查找 Web service 模块组件的逻辑名称。建议所有 service 的引用名称以/service/ 开头。

service-interface 定义了客户端依赖的 JAX-WS Service接口的完全限定类名称。在大多数情况下，这个值是 javax.xml.rpc.Service。也可以指定一个 JAX-WS 生成的服务接口类。

wsdl-file 元素包含了 WSDL 文件的 URI 位置。这个位置相对于模块根目录。

jaxrpc-mapping-file 包含了描述应用程序使用的 Java 接口和 wsdl-file 中的 WSDL 描述之间的 JAX-WS 映射的文件名。这个文件名是一个模块文件中的相对路径。

service-qname 元素声明了具体的被称为 WSDL 的服务元素。如果没有声明 wsdl-file，则不需要指定。

port-component-ref 元素声明了一个在容器中解析服务终端接口到一个 WSDL 端口的客户端依赖关系。它使用一个特别的端口组件选择性地关联服务终端接口。这仅被容器用于 Service.getPort(Class) 方法调用。

handler 元素为端口组件声明处理器。处理程序可以使用 HandlerInfo 接口访问 init-param 名值对。如果未指定 port-name ， 处 理 器 将 与 service 的 所 有 端 口 关 联 。 详 细 信 息 请 参 阅 JSR-109 规 范。不属于 Java EE 实现的容器不要求支持这个元素。

24、 resource-ref 元素

resource-ref 元素包含了部署组件对外部资源的引用声明。

res-ref-name 指定了一个资源管理器连接工厂引用的名称。这个名称是一个相对于 java:com/env 上下文的 JNDI 名称。在部署文件中这个名称必须是唯一的。

res-type 元素指定数据源的类型。该类型是一个希望由数据源实现的 Java 语言类或接口的完全限定名。

res-auth 指定部署组件代码是否以编程方式注册到资源管理器，或容器是否将代表的部署组件注册到资源管理器。如果是第二种情况，容器使用部署器提供的信息。

res-sharing-scope 指定了通过给定的资源管理器连接工厂引用获取的连接是否可以共享。如果指定了这个值，它必须是 Shareable 或Unshareable。

可选的 injection-target 元素用于定义把指定的资源注入到字段或 JavaBean 属性。

25、 resource-env-ref 元素

resource-env-ref 包含了部署组件和对部署组件环境中的资源有关的管理对象的引用。

resource-env-ref-name指定了资源环境引用的名称。它的值是部署组件代码中使用的环境入口名称，它是一个相对于 java:comp/env 上下文的 JNDI 名称，并且在部署组件中必须是唯一的。

resource-env-ref-type 指定了资源环境引用的类型。它是一个 Java 语言类或接口的完全限定名。

可选的 injection-target 元素用于定义把指定的资源注入到字段或 JavaBean 属性。

必须提供 resource-env-ref-type 除非指定了注入目标，在这种情况下，将使用目标的类型。如果两者都指定，该类型必须与注入目标的类型兼容。

26、 message-destination-ref 元素

message-destination-ref 元素包含了部署组件和对部署组件环境中的资源有关的消息目标的引用声明。

message-destination-ref-name 元素指定了一个消息目标引用的名称，它的值是部署组件代码中使用的环境入口名称。这个名称是一个相对于 java:comp/env 上下文的 JNDI 名称，并且在企业 bean 的 ejb-jar 中或其他部署文件中必须是唯一的。

message-destination-type 指定了目标的类型。这个类型由希望目标实现的 Java 接口指定。 message-destination-usage 指定了引用表示的消息目标的用法。这个值表示是使用目标信息中的消息，还是产生目标消息，亦或两者兼而有之。汇编器将使用此信息来连接目标的生产者与消费者。

message-destination-link 把一个消息目标引用或消息驱动 bean 连接到一个消息目标。汇编器设置这个值来反映应用程序中的生产者和消费者消息流。

这个值必须是同一个部署文件或同一个 Java EE 应用程序单元的另一个部署文件中的消息目标的 message-destination-name。或者，这个值可以由一个路径名称组成，使用目标添加的 message-destination-name 和通过"#"分隔路径名称说明一个部署文件包含引用的消息目标。这个路径名称是相对于部署文件，包含引用消息目标的部署组件。这允许多个消息目标使用相同的名称作为唯一标识。可选的 injection-target 元素用于定义把指定的资源注入到字段或 JavaBean 属性。必须指定 message-destination-type 除非注入目标已经指定，在这种情况下，将使用目标的类型。如果两者都指定，该类型必须与注入目标的类型兼容。

27、 message-destination 元素

message-destination 指 定 消 息 的 目 标 。 这 个 元 素 所 描 述 的 逻 辑 目 标 由 部 署 器 映 射 到 物 理 目 标 。

message-destination-name 元素指定了消息目标的名称。该名称在部署文件的消息目标名称中必须是唯一的。

28、 locale-encoding-mapping-list 元素

locale-encoding-mapping-list 包含了语言环境和编码之间的映射。由子元素 locale-encoding-mapping 指定。

14.5 实例

略