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

qfstudying

浏览: 1851 次
性别:
来自: 合肥

最近访客更多访客>>

woodding2008

博主相关

博客

微博

相册

留言

关于我

文章分类

社区版块

存档分类

博客分类：

Java EE

Servlet3.1 文档翻译 Servlet规范

//---------------------------------------------------------------------------------------------//
//-- 原本是响应某童鞋的号召才翻译此文的，不过今天打开草稿箱正准备继续翻译时，       ---//
//-- 发现开涛童鞋已经发布了，后续内容翻译建议大家参考开涛童鞋的文章吧！                 ---//
//-- 附件里我附上了 Servlet3.1官方规范。                                                                      ---//
//----------------------------------------------------- ----------------------------------------//

本章将详细说明Java Servlet 规范3.0版本对容器支持部署描述符的要求。部署描述符在开发者、系统集成人员、应用部署人员之间传达Web应用元素配置信息。

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

web-app 元素
本元素是WEB应用部署描述符(文件)的根元素，包含下列子元素，这个元素有一个必选属性version用于指定当前描述符遵循哪个版本的模式。这个元素下的所有子元素可以是任意顺序。
图14-1 web-app 元素结构
description元素
本元素提供对父元素的描述文本。这个元素不仅出现在web-app中，也出现在多个其他元素中。它有一个可选属性 xml:lang，用来说面描述内容是用是何种语言，默认值为"en"。
display-name元素
本元素包含一个用于工具显示的短名称，这个名称不必是唯一的。元素(同样也)包含一个可选属性 xml:lang , 用于指定(名称)的语言。
icon元素
本元素包含small-icon和large-icon两个元素，分别用来指定小号和大号gif或者jpg格式的图标文件，图标用于在GUI工具中代表父元素。
distributable元素
本元素用于表名当前WEB应用适合部署到一个分布式Servlet容器中。
context-param元素
本元素用于声明若干个WEB应用Servlet上下文初始参数。
filter元素
本元素用于在WEB应用中声明一个过滤器。过滤器被映射到一个Servlet或者在filter-mapping元素中URL模式，用filter-name值去引用它。过滤器在运行时能通过FilterConfig接口来访问在部署描述符(文件)中声明的初始参数。filter-name元素值是filter元素的逻辑名称，它在整个WEB应用范围内必须是唯一的，内容一定不能为空。filter-class元素包含的是过滤器的全类名。init-param 元素包含作为过滤器初始参数的"名-值"对。async-supported是可选元素，它如果被指定，表示过滤器支持异步请求。
图14-2 filter 元素结构
fiter-mapping元素
容器通过这个约束确定哪个过滤器以什么顺序应用到一个请求，filte-name元素的值必须是部署描述符(文件)中声明的一个，匹配的请求可以被指定url-pattern或者servlet-name。
图14-3 filter-mapping 元素结构
listener元素
本元素表示一个应用监听器的部署属性。子元素listener-class声明一个类，这个类必须被注册为WEB应用的监听器，其值是监听器类的全类名。

//----------------------------------------------------------------------------------------------//
//-- 原本是响应某童鞋的号召才翻译此文的，不过今天打开草稿箱正准备继续翻译时，     ---//
//-- 发现开涛童鞋已经发布了，后续内容翻译建议大家参考开涛童鞋饿文章吧！                 ---//
//-- 附件里我附上了 Servlet3.1官方规范                                                                           ---//
//------------------------------------------------ ---------------------------------------------//
servlet元素
本元素用于声明一个Servlet，包含Servlet说明数据。
servlet-mapping元素
session-config元素
mime-mapping元素
welcome-file-list元素
error-page元素
jsp-config元素
security-constraint元素
login-config元素
security-role元素
env-enry元素
ejb-ref元素
ejb-local-ref元素
service-ref元素
resource-ref元素
resource-evn-ref元素
message-destination-ref元素
message-destination元素
local-encoding-mapping-list元素