Servlet 3.0 之 部署描述符

本章为部署描述符中Web容器支持详细描述Java Servlet 规范3.0版本要求。部署描述符在应用开发者，应用组装者和部署者之前传达一个Web应用的元素和配置信息。
对Java Servlet2.4及以上版本，部署描述符按照XML模式文档的方式被定义。
为了向后兼容使用2.2版本API的应用的应用，Web容器也需要支持2.2版本的部署描述符。为了向后兼容使用2.3版本API的应用的应用，Web容器也需要支持2.3版本的部署描述符。2.2版本，2.3版本。

一、部署描述符元素
下列配置和部署信息的类型被要求在Web应用部署描述符中对所有servlet容器都被支持：

• ServletContext初始化参数
• Session配置
• Servlet声明
• Servlet映射
• 应用生命周期监听类
• Filter定义和Filter映射
• MIME类型映射
• 欢迎文件列表
• 错误页面
• Locale和编码映射
• 安全配置，包括登录配置，安全限制，安全角色，安全角色引用和运行方式

二、处理部署描述符的规则

本节列出了一些通用规则，Web容器和开发者必须注意一个Web应用的部署描述符的处理。

• Web容器必须为部署描述符的文本节点的元素内容移除所有前导和后缀空格，在XML1.0中这被定义为"S(white space)"。
• 部署描述符必须对模式有效。操作Web应用的Web容器和工具有很多选择来检查一个WAR的有效性。这包括检查部署描述符文档的有效性。
  此外，推荐操作Web应用的Web容器和工具提供一层语义检查。在非一致性的Web应用case中，工具和容器应该通知开发者描述性的错误信息。高端应用服务器提供商被鼓励以工具和容器分离的方式提供这种有效性检查。
• 在本规范中，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中的项目。distributale的多次出现必须像distributable单次出现一样对待。
• 在部署描述符中指定的URI路径被认为是URL编码格式。当URL包含CR(#xD)或者LF(#xA)时，容器必须通知开发者一个描述性错误信息。容器必须保留URL中所有其它包含空格的字符。
• 容器必须尝试规范部署描述符中的路径。比如，/a/../b格式的路径必须被解析为/b。对以'../'开头的路径的路径开始或者解析在部署描述符中不是有效路径。
• 指向一个相对WAR根路径的资源，或者一个映射相对于WAR根路径的路径的URI路径，除非特殊说明，都应该以前导'/'开头。
• 值是枚举类型元素，值对大小写敏感。

三、部署描述符

本规范的部署描述符地址。

四、部署描述符图

本节说明部署描述中的元素。属性并没有展示在这个图中。

1. web-app 元素
   web-app元素对一个Web应用而言，是部署描述符根。元素包含下列元素。这个元素有一个必须的元素version来指定部署描述符遵守哪个版本的规范。这个元素下的所有子元素能够以任意顺序出现。
   图4-1 web-app 元素结构
   web-app元素结构
2. description元素
   description元素用来提供对父级元素的一个文本描述。这个元素不仅出现在web-app元素中，也会出现在其它多个元素中。它有个可选的属性xml:lang来表明在描述中使用哪种语言。属性的默认值是English("en")。
3. display-name元素
   display-name包含一个简写名字，它用来被工具展示。这个显示名字不必唯一。这个元素有一个可选的属性xml:lang来指明语言。
4. icon元素
   icon元素包含小图和大图元素，它们用来为代表GUI工具中父级元素的小的和大的GIF或者JPEG图标指明文件名。
5. distributable元素
   distributable元素表明Web应用适当地编码来被部署到一个分布式servlet容器中。
6. context-param元素
   context-param包含一个Web应用的servlet上下文初始化参数的声明。
7. filter元素
   filter在Web应用中声明了一个filter。在filter-mapping元素中使用filter-name值引用，filter被映射到一个servlet或者一个URL模式上。Filters能够在运行时通过FilterConfig接口访问部署描述符中声明的初始化参数。filter-name元素的元素内容一定不能为空。filter-class是filter的完整类名。init-param元素包含name-value对来作为filter的初始化参数。可选的async-supported元素表明filter支持异步请求处理。
   图4-2 filter元素结构
   filter元素结构
8. filter-mapping元素
   filter-mapping被容器用来决定哪些filters以什么顺序应用在一个请求上。filter-name的值必须要是在部署描述符中声明的filter。匹配请求能够用url-pattern或者servlet-name指明。
   图4-3 filter-mapping元素结构
   filter-mapping元素结构
9. listener元素
   listener元素为一个应用listener bean表明部署properties。子元素listener-class声明：应用中的一个class必须被注册为一个Web应用listener bean。值是listener类的全路径名。
   图4-4 listener 元素结构
   listener 元素结构
10. servlet元素
    servlet被用来声明一个servlet。它包含了一个servlet的声明数据。jsp-file元素包含了一个Web应用中以一个'/'开头的JSP文件的完整路径。如果一个jsp-file被指明，并且load-on-startup元素出现，那么JSP被重新编译和加载。servlet-name元素包含了servlet的规范名字。每个servlet名字在web应用中是唯一的。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选择servlet的加载顺序。security-role-ref元素在组件里或者在一个部署组件代码中声明了安全角色引用。它由可选的description，在代码（role-name）中使用的安全角色名字以及一个对安全角色（role-link）的可选链接组成。如果安全角色没有被指明，部署者必须选择一份合适的安全角色。可选的async-supported元素表明servlet能够支持异步请求处理。如果一个servlet支持文件上传功能和mime-multipart请求的处理，对同样的配置能够在部署描述符中通过multipart-config元素被提供。multipart-config元素能够被使用来指明文件被存储的位置，文件被上传的最大大小，最大请求大小以及文件被写到磁盘的大小阈值。
    图4-5 servlet元素结构
    servlet元素结构
11. servlet-mapping元素
    servlet-mapping在一个servlet和一个URL模式之间定义了一个映射。
    图4-6 servlet-mapping元素结构
    servlet-mapping元素结构
12. session-config元素
    session-config为Web应用定义了会话参数。子元素session-timeout为所有在Web应用中被创建的会话定义了默认会话超时区间。具体的超时必须通过一个完整的分钟数来表达。如果超时是0或者更少，容器确保会话的默认行为永不超时。如果这个元素没有被指定，容器必须设置它的默认超时周期。
    图4-7 session-config元素结构
    session-config元素结构
13. mime-映射元素
    mime-mapping定义了一个扩展和一个mime类型之间的映射。extension元素包含了一个描述一个扩展的字符串，比如'txt'。
    图4-8 mime-mapping元素结构
    mime-mapping元素结构
14. welcome-file-list元素
    welcome-file-list包含一个欢迎文件的有序列表。子元素welcome-file包含一个文件名来用作一个默认欢迎文件，比如index.html。
    图4-9 welcome-file-list元素结构
    welcome-file-list元素结构
15. error-page元素
    error-page包含一个错误码或者一个异常类型到一个web应用中资源路径的映射。子元素exception-type包含一个Java异常类型的完整类名。子元素location包含了web应用中相对于web应用根路径的资源位置。位置的值必须有一个前导'/'。
    图4-10 error-page元素结构
    error-page元素结构
16. jsp-config元素
    jsp-config被用来在web应用中为JSP文件提供全局配置信息。它有两个子元素，taglib和jsp-property-group。taglib元素能够被用来提供一个tag库上的信息，它被web应用中的JSP页面使用。
    图4-11 jsp-config 元素结构
    jsp-config 元素结构
17. security-constraint元素
    security-constraint被用来关联有一个或者多个web资源集合的安全约束。子元素web-resource-collection指明了资源和web应用中应用于那些资源上的HTTP方法的一个子集，一个安全约束会应用在这个web应用上。auth-constraint表明一个应该被允许访问这个资源集合的用户角色。这里使用的role-name必须对应security-role元素的role-name或者是特别保留的角色名字''。如果''和角色名字同时出现，容器把这个解析为所有所有角色。如果没有角色被指定，没有用户被允许访问Web应用中被security-constraint描述的部分。当决定访问时，容器匹配角色名字对大小写敏感。user-data-constraint表明数据怎样在客户端之前交流，并且容器应该通过子元素transport-guarantee来被保护。transport-guarantee的合法值是NONE，INTEGRAL或者CONFIDENTIAL。
    图4-12 security-constraint 元素结构
    security-constraint 元素结构
18. login-config元素
    login-config被用来配置应该被使用的认证方法，应该被使用的realm名字以及被表单登录机制所需的属性。子元素auth-method为web应用配置认证机制。元素内容必须是BASIC，DIGEST，FORM，CLIENT或者一个具体提供商认证规范。realm-name指明了realm名字，它被用来为认证规范选择web应用。form-login-config指明了应该在表单提交中被使用的登录和错误页面。如果基于表单登录没有被使用，这些元素将会被忽略。
    图4-13 login-config元素结构
    login-config元素结构
19. security-role元素
    security-role定义了一个安全角色。子元素role-name定义了安全角色的名字。这个名字必须为NMTOKEN遵循字典规则。
    图4-14 security-role元素结构
    security-role元素结构
20. env-entry元素
    env-entry声明了一个应用的环境入口。子元素env-entry-name包含一个部署组件环境入口的名字。这个名字是相对于java:comp/env上下文的JNDI名字。名字在部署描述符中必须唯一。env-entry-type包含环境入口值的完整Java类型，应用代码需要这个环境变量的入口值。子元素env-entry-value定义了一个部署逐渐环境入口的值。这个值必须是一个字符串，这个字符串对指定类型的构造函数有效，这个构造函数需要一个字符串作为参数，或者一个java.lang.Character类型的单个字符。可选的injection-target元素被用来把命名的资源注入定义到域或者JavaBean properties中。一个injection-target指定了一个类和一个资源被注入进来来的类的名字。injection-target-class为被注入类指定了完整的类路径名。injection-target-name在具体类里制定了类名。第一个被找到的目标作为JavaBean property名字。如果没有没找到，找到的目标走位一个域名。具体的资源将会在类初始化期间通过调用set方法或者把值设置到名字域里来被注入到目标里。如果一个injection-target为环境入口被指明，env-entry-type可以被忽略或者必须匹配注入对象的类型。如果没有指定injection-target，那么env-entry-type是必须要的。
    图4-15 env-entry 元素结构
    env-entry元素结构
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引用。除了这些元素，injection-target元素能够被用来定义被命名企业bean注入到一个组件域或者property中。
    图4-16 ejb-ref元素结构
    ejb-ref元素结构
22. ejb-local-ref元素
    ejb-local-ref声明了指向企业bean的本地home的引用。local-home定义了企业bean的本地home接口的完整名字。local定义了企业bean的本地引用的完整名字。
    图4-17 ejb-local-ref元素结构
    ejb-local-ref元素
23. service-ref元素
    service-ref声明了指向一个Web服务的引用。service-ref-name声明了逻辑名字，模块中的组件使用这个名字来查找Web服务。推荐所有服务应用名字都以/service/开头。service-interface定义了客户端依赖的JAX-WS服务接口完整类名。大多数场景中，值将会是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元素声明了一个容器上的客户端依赖来把Service Endpoint Interface解析到一个WSDL端口。给Service Endpoint Interface关联一个特殊端口是可选的。这仅在一个Service.getPort(Class)调用时被容器使用。handler元素为一个端口组件声明了一个处理器。处理器可以使用HandlerInfo接口来访问init-name name-value对。如果port-name没有被指定，处理器被认为与所有服务的端口关联。可以参考JSR-109获得详细信息。
    图4-18 service-ref元素结构
    service-ref元素结构
24. resource-ref 元素
    resource-ref包含一个部署组件引用一个外部资源的声明。res-ref-name指明了一个资源管理连接工厂引用的名字。名字是相对于java:comp/env上下文的JNDI名字。名字在部署文件中必须唯一。res-type元素指明了数据源的类型。类型是完整的Java语言类或者被数据源实现的接口。res-auth指明了部署组件代码是否编程式地登记到资源管理，或者容器是否根据部署组件登记到资源管理。对于后面一种情况，容器使用部署者提供的信息。res-sharing-scope指明了通过特定资源管理连接工厂引用获取的连接是否能被共享。如果被指定，值必须是Shareable或者Unshareable。可选的injection-target元素被用来把命名的资源注入到fields或者Javabeans properties中。
    图4-19 resource-ref元素结构
    resource-ref元素结构
25. resource-env-ref元素
    resource-env-ref包含了部署组件的引用，它指向部署组件环境中与一个资源关联的被管理的对象。resource-env-ref-name指明了资源环境引用的名字。值是在部署组件中代码中被使用的环境入口名字和一个相对java:comp/env上下文的JNDI名字，并且在部署组件中必须唯一。resource-env-ref-type指明了资源环境引用的类型。它是一个Java语言类或者接口的完整名字。可选的injection-target元素被用来定义把命名资源注入到fields或者JavaBeans properties中。resource-env-ref-type必须被提供，除非一个注入目标被指明。如果否被指明，类型必须兼容注入目标的类型。
    图4-20 resource-env-ref元素结构
    resource-env-ref元素结构
26. message-destination-ref元素
    message-destination-ref包含了一个部署组件引用的声明，它指向一个与部署组件环境中与一个资源关联的消息目标。message-destination-ref-name元素指明了一个消息目的地引用的名字。它的值是在部署组件代码中被使用的环境入口名字。名字是一个相对java:comp/env上下文的JNDI名字，并且在一个企业beans的ejb-jar或者其它的部署文件中必须唯一。message-destination-type指明了目的地的类型。类型通过将会被实现的Java接口指定。message-destination-usage指明了通过引用表明的消息目的地的使用。值表明了消息是否会从消息目的地被消费，是否会为目的地生产消息，或者两者皆是。组装者利用这些信息把一个目的地的生产者与它的消费者关联起来。message-destination-link链接了一个消息目的地引用或者消息启动bean到一个消息目的地。组装者设置这个值来反应应用中生产者和消费者之间的信息流。值必须是相同部署文件或者相同Java EE应用单元其它部署文件中一个消息目的地的message-destination-name。值可以由一个路径名字组成，这个名字指明了一个部署文件，它包含了被引用消息目的地，目的地在路径名中通过“#”追加或者分隔。路径名相对于部署文件，它包含引用消息目的地的部署组件。这允许有相同名字的多个消息目的地被确定唯一身份。可选的injection-target元素被用来定义命名资源到fields或者JavaBeans properties的注入。message-destination-type必须被指明，除非一个注入目标被指明，这种情形下目标的类型会被使用。如果都被指定，类型必须与注入目标类型兼容。
    例子：
    <message-destination-ref>
    <message-destination-ref-name>
    jms/StockQueue
    </message-destination-ref-name>
    <message-destination-type>
    javax.jms.Queue
    </message-destination-type>
    <message-destination-usage>
    Consumes
    </message-destination-usage>
    <message-destination-link>
    CorporateStocks
    </message-destination-link>
    </message-destination-ref>
    图4-21 message-destination-ref元素结构
    message-destination-ref元素结构
27. message-destination元素
    message-destination指明了一个消息目的地。这个元素描述的逻辑目的地被部署者映射到一个物理目的地。message-destination-name元素为一个消息目的地指明了一个名字。在部署文件中，这个名字在消息目的地名字间必须唯一。
    例子：
    <message-destination>
    <message-destination-name>
    CorporateStocks
    </message-destination-name>
    </message-destination>
    图4-22 message-destination元素结构
    message-destination元素结构
28. locale-encoding-mapping-list元素
    locale-encoding-mapping-list包含locale和encoding之间的映射，它通过子元素locale-encoding指定。
    例子：
    <locale-encoding-mapping-list>
    <locale-encoding-mapping>
    <locale>ja</locale>
    <encoding>Shift_JIS</encoding>
    </locale-encoding-mapping>
    </locale-encoding-mapping-list>
    图4-23 locale-encoding-mapping-list元素结构
    locale-encoding-mapping-list元素结构

五、例子

下列例子说明了在部署描述符规范中列出的定义的使用。

1. 图5-1 基本部署描述符例子
   <?xml version="1.0" encoding="ISO-8859-1"?>
   <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd” version=”2.5”>
   <display-name>A Simple Application</display-name>
   <context-param>
   <param-name>Webmaster</param-name>
   <param-value>webmaster@mycorp.com</param-value>
   </context-param>
   <servlet>
   <servlet-name>catalog</servlet-name>
   <servlet-class>com.mycorp.CatalogServlet</servlet-class>
   <init-param>
   <param-name>catalog</param-name>
   <param-value>Spring</param-value>
   </init-param>
   </servlet>
   <servlet-mapping>
   <servlet-name>catalog</servlet-name>
   <url-pattern>/catalog/*</url-pattern>
   </servlet-mapping>
   <session-config>
   <session-timeout>30</session-timeout>
   </session-config>
   <mime-mapping>
   <extension>pdf</extension>
   <mime-type>application/pdf</mime-type>
   </mime-mapping>
   <welcome-file-list>
   <welcome-file>index.jsp</welcome-file>
   <welcome-file>index.html</welcome-file>
   <welcome-file>index.htm</welcome-file>
   </welcome-file-list>
   <error-page>
   <error-code>404</error-code>
   <location>/404.html</location>
   </error-page>
   </web-app>

2. 安全的例子
   例5-2 使用安全的部署描述符
   <?xml version="1.0" encoding="ISO-8859-1"?>
   <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd” version=”2.5”>
   <display-name>A Secure Application</display-name>
   <servlet>
   <servlet-name>catalog</servlet-name>
   <servlet-class>com.mycorp.CatalogServlet</servlet-class>
   <init-param>
   <param-name>catalog</param-name>
   <param-value>Spring</param-value>
   </init-param>
   <security-role-ref>
   <role-name>MGR</role-name>
   
   <role-link>manager</role-link>
   </security-role-ref>
   </servlet>

     <security-role> 
       <role-name>manager</role-name> 
     </security-role> 
     <servlet-mapping> 
       <servlet-name>catalog</servlet-name> 
       <url-pattern>/catalog/*</url-pattern> 
     </servlet-mapping> 
     <security-constraint> 
       <web-resource-collection>
         <web-resource-name>SalesInfo </web-resource-name>     
         <url-pattern>/salesinfo/*</url-pattern> 
         <http-method>GET</http-method> 
         <http-method>POST</http-method>
       </web-resource-collection> 
      <auth-constraint>
        <role-name>manager</role-name> 
      </auth-constraint> 
      <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL </transport-guarantee>
      </user-data-constraint>
    </security-constraint>
   </web-app>
   

翻译自 Java Servlet Specification
Version 3.0 Rev a
Author:Rajiv Mordani
Date: December 2010