Servlet规范之部署描述符

Posted 顧棟

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Servlet规范之部署描述符相关的知识，希望对你有一定的参考价值。

Deployment Descriptor

文章是对 JSR-000340 JavaTM Servlet 3.1 Final Release的Java™ Servlet规范的翻译，尚未校准

文章目录

本章规定了 Java™ Servlet 规范对 Web 容器支持部署描述符的要求。部署描述符在应用程序开发人员、应用程序装配人员和部署人员之间传递 Web 应用程序的元素和配置信息。

对于Java Servlets v.2.4及以上版本，部署描述符是以XML模式文档的形式定义的。

为了使写在2.2版API上的应用程序向后兼容，还要求Web容器支持2.2版的部署描述符。为了使写给2.3版API的应用程序向后兼容，还要求Web容器支持2.3版的部署描述符。2.2版本可在http://java.sun.com/j2ee/dtds/web-app_2_2.dtd，2.3版本可在http://java.sun.com/dtd/web-app_2_3.dtd。

部署描述符元素

在所有Servlet容器的Web应用部署描述符中，需要支持以下类型的配置和部署信息:

  • ServletContext初始参数
  • Session 配置
  • Servlet声明
  • Servlet映射
  • 应用程序生命周期监听器类
  • 过滤器定义和过滤器映射
  • MIME类型映射
  • 欢迎文件列表
  • 错误页面
  • 本地化和编码映射
  • 安全配置，包括登录配置、安全限制、安全角色、安全角色参考和运行状态

部署描述符的处理规则

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

  • Web容器必须为部署描述符的文本节点的元素内容删除所有前导和尾部的空白，这些空白在XML 1.0（http://www.w3.org/TR/2000/WD-xml-2e-20000814）中被定义为 “S（white space）”。

  • 部署描述符必须对schema有效。操作Web应用程序的Web容器和工具有广泛的选项来检查WAR的有效性。这包括检查其中持有的部署描述符文件的有效性。

    此外，建议操作Web应用程序的Web容器和工具提供一定程度的语义检查。例如，应该检查安全约束中引用的角色是否与部署描述符中定义的安全角色的名称相同。

    在不符合要求的Web应用程序的情况下，工具和容器应该用描述性的错误信息通知开发者。我们鼓励高端应用服务器供应商以独立于容器的工具形式提供这种有效性检查。

  • 在这个版本的规范中，web-app下的子元素可以有任意的顺序。由于XML Schema的限制，元素distributable、session-config、welcome-file-list、jsp-config、login-config和local-encoding-mapping-list的多重性从 "可选 "改为 “0或以上”。当部署描述符包含一个以上的session-config、jsp-config和login-config元素时，容器必须用描述性的错误信息通知开发者。容器必须在welcome-file-list和local-encodingmapping-list中的项目多次出现时将其连接起来。多次出现的 distributable 必须以与单次出现的 distributable 完全相同的方式处理。

  • 部署描述符中指定的URI路径被假定为URLdecoded形式。当URL包含CR(#xD)或LF(#xA)时，容器必须用描述性的错误信息通知开发者。容器必须保留所有其他字符，包括URL中的空白。

  • 容器必须尝试将部署描述符中的路径规范化。例如，形式为/a/…/b的路径必须被解释为/b。在部署描述符中，以…/开始或解析为路径的路径不是有效的路径。

  • 指向相对于WAR根的资源的URI路径，或相对于WAR根的路径映射，除非另有规定，应该以前面的/开始。

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

部署描述符

该规范修订版的部署描述符可在以下网址找到 http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd

部署描述符示意图

本节说明了部署描述符中的元素。属性没有在图中显示。详细信息请参见部署描述符模式。

web-app元素

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

description Element

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

display-name Element

显示名称包含一个打算由工具显示的短名称。该显示名称不需要是唯一的。这个元素有一个可选的属性xml:lang来指定语言。

icon Element

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

distributable Element

可分发表示该Web应用程序被适当编程以部署到分布式Servlet容器中。

context-param Element

context-param包含了一个Web应用的servlet上下文初始化参数的声明。

filter Element

filter在Web应用程序中声明了一个过滤器。过滤器在filter-mapping元素中被映射到一个servlet或一个URL模式，使用filter-name值来引用。过滤器可以在运行时通过FilterConfig接口访问部署描述符中声明的初始化参数。filter-name元素是过滤器的逻辑名称。它在Web应用程序中必须是唯一的。filter-name元素的内容不能是空的。filter-class是过滤器的完全合格的类别名称。init-param元素包含名-值对，作为这个过滤器的初始化参数。可选的async-supported元素，当被指定时，表示该过滤器支持异步请求处理。

FIGURE 14-2 filter Element Structure

filter-mapping Element

过滤器映射被容器用来决定哪些过滤器要以什么顺序应用于请求。过滤器名称的值必须是部署描述符中的过滤器声明之一。匹配的请求可以指定url-pattern或servlet-name。

FIGURE 14-3 filter-mapping Element Structure

listener Element

监听器表示应用程序监听器bean的部署属性。子元素listener-class声明应用程序中的一个类必须被注册为Web应用程序监听器bean。该值是监听器类的完全合格的类名。

FIGURE 14-4 listener Element Structure

servlet Element

servlet是用来声明一个servlet的。它包含一个servlet的声明性数据。jsp-file元素包含了Web应用程序中以"/"开头的JSP文件的完整路径。如果指定了jsp-file，而且load-onstartup元素也存在，那么JSP应该被预编译和加载。servlet-name元素包含servlet的标准名称。每个servlet名称在Web应用程序中都是唯一的。servletname元素的内容不能是空的。servlet-class包含servlet的完全合格的类名。run-as元素指定了用于执行组件的身份。它包含一个可选的描述，以及由role-name元素指定的安全角色的名称。load-onstartup元素表示这个servlet应该在Web应用的启动时被加载（实例化并调用其init()）。这个元素的内容必须是一个整数，表示Servlet应该被加载的顺序。如果该值是一个负的整数，或者该元素不存在，那么容器就可以自由地在它选择的时候加载servlet。如果该值是一个正整数或0，则容器必须在应用程序部署时加载并初始化servlet。容器必须保证标记为较低整数的 servlet 在标记为较高整数的 servlet 之前被加载。容器可以选择具有相同 load-on-startup 值的 servlet 的加载顺序。security-role-ref元素声明了组件或部署组件代码中的安全角色引用。它由一个可选的描述、代码中使用的安全角色名称（role-name）和一个可选的安全角色链接（role-link）组成。如果没有指定安全角色，部署者必须选择一个适当的安全角色。如果指定了可选的asyncsupported元素，则表明Servlet可以支持异步请求处理。如果一个Servlet支持文件上传功能和对mime-multipart请求的处理，那么可以通过描述符中的multipart-config元素提供相同的配置。multipart-config元素可以用来指定存储文件的位置、上传文件的最大尺寸、最大请求尺寸以及文件被写入磁盘的尺寸阈值。

FIGURE 14-5 servlet Element Structure

servlet-mapping Element

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

FIGURE 14-6 servlet-mapping Element Structure

session-config Element

session-config定义了这个Web应用程序的会话参数。子元素session-timeout定义了在此Web应用程序中创建的所有会话的默认会话超时间隔。指定的超时必须以整数分钟表示。如果超时为0或更少，容器就会确保会话的默认行为是永不超时。如果没有指定这个元素，容器必须设置它的默认超时时间。

FIGURE 14-7 session-config Element Structure

mime-mapping Element

mime-mapping定义了扩展和mime类型之间的映射。扩展元素包含描述扩展的字符串，如 “txt”。

FIGURE 14-8 mime-mapping Element Structure

welcome-file-list Element

welcome-file-list包含一个有序的欢迎文件列表。子元素welcome-file包含一个文件名，作为默认的欢迎文件，如index.html。

FIGURE 14-9 welcome-file-list Element Structure

error-page Element

error-page包含一个错误代码或异常类型与Web应用程序中的资源路径之间的映射。然而，错误代码或异常类型元素可以被省略，以指定一个默认的错误页面。子元素exception-type包含一个Java异常类型的完全合格的类名。子元素location元素包含网络应用程序中资源相对于网络应用程序根的位置。location的值必须有一个领先的’/'。

FIGURE 14-10 error-page Element Structure

jsp-config Element

jsp-config是用来为Web应用程序中的JSP文件提供全局配置信息。它有两个子元素，taglib和jsp-propertygroup。taglib元素可以用来提供Web应用程序中JSP页面所使用的标签库的信息。详见JavaServer Pages规范2.1版。

FIGURE 14-11 jsp-config Element Structure

security-constraint Element

安全约束（security-constraint）用于将安全约束与一个或多个Web资源集合相关联。子元素 web-resource-collection 指明了 Web 应用程序中适用安全约束的资源子集和这些资源上的 HTTP 方法。auth-constraint表示应该被允许访问这个资源集合的用户角色。这里使用的角色名称必须与为该 Web 应用程序定义的安全角色元素之一的角色名称相对应，或者是特别保留的角色名称"*“，这是表示 Web 应用程序中所有角色的紧凑语法。如果同时出现”*"和角色名称，容器将其解释为所有角色。如果没有定义角色，就不允许用户访问包含安全约束的 Web 应用的部分。在确定访问权时，容器会敏感地匹配角色名称的大小写。User-data-constraint 表示在客户机和容器之间通信的数据应该如何被子元素 transport-guarantee 所保护。运输保证的合法值是 NONE、INTEGRAL 或 CONFIDENTIAL 中的一个。

FIGURE 14-12 security-constraint Element Structure

login-config Element

login-config用于配置应该使用的认证方法、该应用应该使用的境界名称以及表单登录机制需要的属性。子元素authmethod配置了Web应用程序的认证机制。该元素的内容必须是BASIC、DIGEST、FORM、CLIENT-CERT或供应商特定的认证方案。realm-name表示为Web应用程序选择的认证方案所使用的领域名称。form-login-config指定了在基于FORM的登录中应该使用的登录和错误页面。如果不使用基于FORM的登录，这些元素将被忽略。

FIGURE 14-13 login-config Element Structure

security-role Element

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

FIGURE 14-14 security-role Element Structure

env-entry Element

env-entry声明了一个应用程序的环境条目。子元素 env-entry-name 包含一个部署组件的环境条目的名称。该名称是相对于 java:comp/env 上下文的 JNDI 名称。该名称在部署组件中必须是唯一的。env-entry-type 包含应用程序的代码所期望的环境条目值的完全限定的 Java 类型。子元素 env-entry-value 指定了部署组件的环境条目的值。该值必须是一个字符串，它对指定类型的构造器有效，该构造器需要一个字符串作为参数，或者对java.lang.Character来说是一个单一字符。可选的注入目标（injection-target）元素用于定义将命名的资源注入到字段或JavaBeans属性中。注入目标指定了一个类和该类中的一个名称，资源应该被注入该类中。注入-目标-类指定了作为注入目标的完全合格的类名。注入-目标-名称指定了指定类中的目标。目标首先作为一个JavaBean属性名被寻找。如果没有找到，目标将作为一个字段名来寻找。在类的初始化过程中，指定的资源将通过调用目标属性的set方法或在name文件中设置一个值而被注入到目标中。如果为环境条目指定了一个注入目标，enventry-type可以省略，或者必须与注入目标的类型匹配。如果没有指定注入目标，env-entry-type是必需的。

FIGURE 14-15 env-entry Element Structure

ejb-ref Element

ejb-ref声明了对企业Bean的引用。ejb-refname指定了在引用企业Bean的部署组件的代码中使用的名称。ejb-ref-type是被引用的企业Bean的预期类型，它是实体或会话。home定义了被引用的企业Bean的主接口的完全合格名称。remote定义了被引用的企业Bean的远程接口的完全合格的名称。ejb-link指定一个EJB引用被链接到企业Bean。更多细节请参见Java Platform, Enterprise Edition, version 6。除了这些元素外，注入目标（injection-target）元素可用于定义将命名的企业Bean注入到组件字段或属性中。

FIGURE 14-16 ejb-ref Element Structure

ejb-local-ref Element

ejb-local-ref声明了对企业Bean的本地首页的引用。local-home定义了企业Bean的本地接口的完全合格名称。local定义了企业Bean的本地接口的完全合格名称。

FIGURE 14-17 ejb-local-ref Element Structure

service-ref Element

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 接口与wsdlfile 中的 WSDL 描述之间的 JAX-WS 映射。文件名是模块文件中的一个相对路径。服务qname "元素声明了被引用的特定 WSDL 服务元素。如果没有声明 wsdl-file，则不指定它。Port-component-ref元素声明了客户对容器的依赖性，以便将服务端点接口解析为 WSDL 端口。它可以选择将服务端点接口与特定的 port-component联系起来。这只被容器用于 Service.getPort(Class) 方法的调用。handler元素声明了 port-component 的处理程序。处理程序可以使用HandlerInfo接口访问init-param名-值对。如果没有指定port-name，处理程序将被假定与服务的所有端口相关。详见JSR-109规范[http://www.jcp.org/en/jsr/detail?id=109]。不属于 Java EE 实现的容器不需要支持这个元素。

FIGURE 14-18 service-ref Element Structure

resource-ref Element

resource-ref包含部署组件对外部资源引用的声明。res-ref-name指定了一个资源管理器连接工厂引用的名称。该名称是相对于java:comp/env上下文的JNDI名称。该名称在部署文件中必须是唯一的。res-type元素指定了数据源的类型。该类型是完全合格的Java语言类或预期由数据源实现的接口。res-auth指定部署组件代码是否以编程方式登录到资源管理器，或者容器是否将代表部署组件登录到资源管理器。在后一种情况下，容器使用由部署者提供的信息。res-sharing-scope指定了通过给定的资源管理器连接工厂引用获得的连接是否可以被共享。如果指定的话，该值必须是可共享或不可共享的。可选的injection-target元素用于定义将命名的资源注入到字段或JavaBeans属性中。

FIGURE 14-19 resource-ref Element Structure

resource-env-ref Element

resource-env-ref包含部署组件对与部署组件环境中的资源有关的管理对象的引用。resource-env-ref-name指定了资源环境引用的名称。该值是部署组件代码中使用的环境条目名称，是相对于java:comp/env上下文的JNDI名称，在部署组件中必须是唯一的。resource-env-ref-type指定了资源环境引用的类型。它是一个Java语言类或接口的完全限定名称。可选的注入目标（injection-target）元素用于定义将命名的资源注入到字段或JavaBeans属性。除非指定了注入目标，否则必须提供resource-env-ref-type，在这种情况下，将使用目标的类型。如果两者都被指定，类型必须与注入目标的类型赋值兼容。

FIGURE 14-20 resource-env-ref Element Structure

message-destination-ref Element

message-destination-ref元素包含部署组件对与部署组件环境中的资源相关的消息目的地的引用声明。message-destination-ref-name元素指定了消息目的地引用的名称；其值是部署组件代码中使用的环境条目名称。该名称是相对于java:comp/env上下文的JNDI名称，对于企业Bean来说，在ejb-jar中必须是唯一的，对于其他Bean来说，在部署文件中也是唯一的。message-destination-type指定目的地的类型。该类型由预期由目的地实现的Java接口指定。message-destination-usage指定引用所指示的消息目的地的使用。该值表示消息是否从消息目的地消费，为目的地生产，或两者都是。汇编器利用这一信息将目的地的生产者和消费者联系起来。message-destination-link 将一个消息目的地参考或消息驱动的bean链接到一个消息目的地。汇编者设置该值以反映应用程序中生产者和消费者之间的消息流。该值必须是同一部署文件中或同一Java EE应用单元中的另一个部署文件中的消息目的地的message-destination-name。或者，该值可以由一个路径名称组成，指定包含参考消息目的地的部署文件，并附加目的地的 message-destination-name ，用 "#"与路径名称分开。路径名是相对于包含引用消息目的地的部署组件的部署文件而言的。这允许具有相同名称的多个消息目的地被唯一地识别。可选的injection-target元素用于定义将命名的资源注入字段或JavaBeans属性中。除非指定了注入目标，否则必须指定消息目的地类型，在这种情况下，将使用目标的类型。如果两者都被指定，类型必须与注入目标的类型赋值兼容。

Example:

<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>

FIGURE 14-21 message-destination-ref Element Structure

message-destination Element

消息目的地（message-destination）指定了一个消息目的地。这个元素所描述的逻辑目的地被部署者映射到物理目的地。message-destination-name元素为消息目的地指定了一个名称。这个名字在部署文件中的消息目的地的名字中必须是唯一的。

Example:

<message-destination>
	<message-destination-name>
		CorporateStocks
	</message-destination-name>
</message-destination>

FIGURE 14-22 message-destination Element Structure

locale-encoding-mapping-list Element

The locale-encoding-mapping-list contains the mapping between the locale and the encoding. specified by the sub-element locale-encoding-mapping.

locale-encoding-mapping-list包含本地和编码之间的映射，由子元素 locale-encoding-mapping指定。

<locale-encoding-mapping-list>
	<locale-encoding-mapping>
		<locale>ja</locale>
		<encoding>Shift_JIS</encoding>
	</locale-encoding-mapping>
</locale-encoding-mapping-list>

FIGURE 14-23 locale-encoding-mapping-list Element Structure

Examples

下面的例子说明了部署描述符模式中所列定义的用法。

A Basic Example

CODE EXAMPLE 14-1 Basic Deployment Descriptor Example

<?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>

An Example of Security

CODE EXAMPLE 14-2 Deployment Descriptor Example Using Security

<?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 name used in code -->
		<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>

以上是关于Servlet规范之部署描述符的主要内容，如果未能解决你的问题，请参考以下文章

Servlet_03_部署描述符

Servlet规范之Web应用

Servlet注释与部署描述符

Servlet3.x部署描述符简介

简述命名xml元素应遵循的规范

jsp 部署