我未翻译完的一段 Servlet 3.1 API 规范之“部署描述符”

Java Servlet 规范v2.4以上版本，部署描述符以XML文档的形式进行定义。

为了向后兼容用v2.2版API编写的应用，要求Web容器也支持v2.3版的部署描述符规范。为了向后兼容用v2.2版API编写的应用，要求Web容器也支持v2.3版的部署描述符规范。

v2.2版部署描述符规范的文档类型定义文件：http://java.sun.com/j2ee/dtds/web-app_2_2.dtd

v2.3版部署描述符规范的文档类型定义文件：http://java.sun.com/dtd/web-app_2_3.dtd.

14.1部署描述符的元素

要求所有Web容器的部署描述符号支持以下配置类型和部署描述信息：

• ServletContext 初始化参数
• 会话配置
• Servlet声明
• Servlet映射
• 应用生命周期监听类
• 过滤器的定义与映射
• MIME类型映射
• 欢迎页面(默认首页)列表
• 错误页面
• 区域与编码映射
• 安全配置，包括 login-config, security-constra int, security-role, security-role-ref and run-as

14.2部署描述符(文件)的处理规则

      本节列出了一些基本的规则，这些规则是容器和开发者在处理一个Web应用部署描述符时必须要注意的地方。

• 容器必须删除其所有部署描述符的文本节点元素内容的前导空白和尾随空白。
• 部署描述必须对模式(XML语法定义)有效。处理WEB应用的WEB容器和工具会从多个方面检查WAR文件的有效性，包括检查WAR文件中是否包含部署描述符文档。
  此外，建议处理WEB应用的容器和工具提供一个标准的语义检查。比如，检查安全约束里引用的角色是否与部署描述里定义的某一个安全角色同名。
  如果WEB应用有不一致性的情况，工具和容器应当给开发者一个描述错误提示消息。对于高端的服务器提供商，鼓励以独立于容器的工具提供这种有效性校验。
• 在本规范中，web-app的子元素可以是任意顺序。由于XML模式的约束，多个可选性元素(distributable ,  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中的空白。
• 容器必须尝试规范化部署描述中的路径，如："/a/../b" 形式的路径必须被解读为"/b"。部署描述符(部署描述文件)中以 "../" 开头或者可以解析成以 "../" 开头的路径都不是合法的路径。
• URI是指相对于WAR包的根目录的资源或者是一个相对于WAR包根目录的映射路径，如果没有特别规定，其应以 "/" 开头。
• 值是枚举类型的元素的值是区分大小写的。

14.3部署描述符
      本版本规范的部署描述符(文件)可以在这里访问: http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd

14.4部署描述符(文件结构)图解
本节阐述部署描述符(文件)中的元素，属性没有显示在插图中，详细信息可参考部署描述符(文件)的模式(文件)。

1. web-app 元素
   本元素是WEB应用部署描述符(文件)的根元素，包含下列子元素，这个元素有一个必选属性version用于指定当前描述符遵循哪个版本的模式。这个元素下的所有子元素可以是任意顺序。
   图14-1 web-app 元素结构
   
2. description元素
   本元素提供对父元素的描述文本。这个元素不仅出现在web-app中，也出现在多个其他元素中。它有一个可选属性 xml:lang，用来说面描述内容是用是何种语言，默认值为"en"。
3. display-name元素
   本元素包含一个用于工具显示的短名称，这个名称不必是唯一的。元素(同样也)包含一个可选属性 xml:lang , 用于指定(名称)的语言。
4. icon元素
   本元素包含small-icon和large-icon两个元素，分别用来指定小号和大号gif或者jpg格式的图标文件，图标用于在GUI工具中代表父元素。
5. distributable元素
   本元素用于表名当前WEB应用适合部署到一个分布式Servlet容器中。
6. context-param元素
   本元素用于声明若干个WEB应用Servlet上下文初始参数。
7. filter元素
   本元素用于在WEB应用中声明一个过滤器。过滤器被映射到一个Servlet或者在filter-mapping元素中URL模式，用filter-name值去引用它。过滤器在运行时能通过FilterConfig接口来访问在部署描述符(文件)中声明的初始参数。filter-name元素值是filter元素的逻辑名称，它在整个WEB应用范围内必须是唯一的，内容一定不能为空。filter-class元素包含的是过滤器的全类名。init-param 元素包含作为过滤器初始参数的"名-值"对。async-supported是可选元素，它如果被指定，表示过滤器支持异步请求。
   图14-2 filter 元素结构
   
    
8. fiter-mapping元素
   容器通过这个约束确定哪个过滤器以什么顺序应用到一个请求，filte-name元素的值必须是部署描述符(文件)中声明的一个，匹配的请求可以被指定url-pattern或者servlet-name。
   图14-3 filter-mapping 元素结构
   
   
    
9. listener元素
   本元素表示一个应用监听器的部署属性。子元素listener-class声明一个类，这个类必须被注册为WEB应用的监听器，其值是监听器类的全类名。
   
   //----------------------------------------------------------------------------------------------//
   //-- 原本是响应某童鞋的号召才翻译此文的，不过今天打开草稿箱正准备继续翻译时，       ---//
   //-- 发现开涛童鞋已经发布了，后续内容翻译建议大家参考开涛童鞋饿文章吧！                 ---//
   //-- 附件里我附上了 Servlet3.1官方规范                                                                           ---//
   //------------------------------------------------ ---------------------------------------------//
   
   
10. servlet元素
    本元素用于声明一个Servlet，包含Servlet说明数据。
11. servlet-mapping元素
12. session-config元素
13. mime-mapping元素
14. welcome-file-list元素
15. error-page元素
16. jsp-config元素
17. security-constraint元素
18. login-config元素
19. security-role元素
20. env-enry元素
21. ejb-ref元素
22. ejb-local-ref元素
23. service-ref元素
24. resource-ref元素
25. resource-evn-ref元素
26. message-destination-ref元素
27. message-destination元素
28. local-encoding-mapping-list元素

14.5示例