本章指定Java TM Servlet规范对Web容器对部署描述符的支持要求，部署描述符在应用程序开发人员，应用程序组装人员和部署人员之间传达web应用程序的元素和配置信息
对于java Servlet v.2.4及更高版本，部署描述符是根据XML模式文档定义的。
为了向使用API2.2版本编写的应用程序向后兼容，还需要web容器支持2.2版本的部署描述符，为了向写入API2.3版本的应用程序向后兼容，还需要web容器支持2.3版本的部署描述符，可以从 http://java.sun.com/j2ee/dtds/web-app_2_2.dtd 获取2.2版本， http://java.sun.com/dtd/web-app_2_3.dtd. 获取2.3版本
14.1、部署描述符元素
- web应用程序部署描述符中需要为所有servlet容器支持以下类型的配置和部署信息
- ServletContext初始化参数
- 会话配置
- servlet声明
- Servlet mapping 映射
- 应用程序生命周期的监听器类
- 过滤器定义和过滤器 mapping 映射
- MIME 类型映射
- 欢迎文件列表
- 错误页面
- 本地化和编码映射
- 安全限制，包含login-config, security-constraint, security-role, security-role-ref 和运行方式
14.2、部署描述符处理规则
- 本节列出了web容器和开发人员在处理web应用程序的部署描述符时必须注意的一些常规规则：
- 在XML1.0(http://www.w3.org/TR/2000/WD-xml-2e-20000814)中，web容器必须移除那些文本标签的文本前导和后缀的空格
- 部署描述符必须对模式有效，操作web应用程序的web容器和工具具有多种检查WAR有效性选项，这包含检查其中保存的部署描述符文档的有效性。
- 此外，建议操作web应用程序的web容器和工具应提供一定级别的语义检查，例如，应检查安全性约束中引用的角色与部署描述符中定义的安全性角色之一具有相同的名称
- 如果web应用程序不一致，则工具和容器向开发人员提供描述性错误消息，鼓励高端应用服务器供应商提供与容器分离的有效性检查工具。
- 在此版本的规范中，web-app下的子元素可以按任意顺序排列，由于XML模式限制，多个distributable,session-config, weblcome-file-list, jsp-config,login-config 和 locale-encoding-mapping-list(都是可以0到更多)，当部署描述包含session-config,jsp-config和login-config多个元素时，容器必须向开发人员提供描述性错误消息，如果出现多次，容器必须将welcome-file-list和locale-encoding-mapping-list中的内容合并，多次出现的distributable必须与一次出现的distributable完全相同。
- 假定在部署描述符中指定的URI路径为URL解码形式。当URL包含回车[CR（#xD)] 或 换行[LF(#xA)]时，容器必须向开发人员提供描述性错误消息，容器必须保留所有其他字符，包括URL中空格
- 容器必须尝试规范化部署描述符中的路径，例如，格式为/a/…/b的路径必须解释为/b,以…/开头的路径开头或解析的路径在部署描述符中不是有效路径。
- 除非另有说明，否则引用相对对于WAR根目录的资源或相对于WAR根目录的路径的URI路径应以/开头。
- 在其值为枚举类型的元素中，该值区分大小写。
14.3、部署描述符
- 该规范修订版的部署描述符可从以下网站获得：http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd
14.4、部署描述符图示
- 本节说明了部署描述符中的元素，属性未在图中显示，有关详情信息，请参见部署描述符架构。
-
web-app 元素
- web-app元素是web应用程序的根元素，该元素包含以下元素，此元素具有必须的属性版本，以指定描述符符合那个模式版本，该元素下的所有子元素可以任意顺序排列。
- web-app图示
-
description 元素
- description元素用于提供描述父元素的文本，该元素不仅出现在web-app元素下，而且还出现在其他多个元素下，它具有可选属性xml:lang, 以指示描述中使用的语言，该属性的默认值为英语(“en”)
-
display-name元素
- 显示名称包含一个旨在工具显示的简称，显示名称不必唯一。该元素具有一个可选属性xml:lang 以指定语言
-
icon 元素
- 该图标包含小图标和大图标元素，这些元素指定用于在GUI工具中表示父元素的大小GIF或JPEG图标图像的文件名
-
distributable 元素
- distribuable指示已对web应用程序进行适当编程，以将其部署到分布式Servlet容器中。
-
context-param 元素
- 上下文参数包含web应用程序的servlet上下文初始化参数的声明。
-
过滤器原始
-
filter表示在web应用程序中声明一个过滤器，使用filter-name的值进行引用，将过滤器到过滤器映射元素中的servlet或URL模式，过滤器可以在运行时通过FilterConfig接口访问在部署描述中声明的初始化参数，filter-name元素是过滤的逻辑名称，它在web应用程序中必须是唯一的，filter-nam元素的元素内容不能为空，filter-class是过滤器的完全限定的类名称（包含包名），init-param元素是包含键值对的过滤器的初始化参数，这个可选的async-supported元素，当它指定的时候表示过滤器支持异步请求过滤处理。
-
过滤器元素的结构
-
-
filter-mapping 元素
- 容器使用过滤器映射来决定将哪些过滤器以什么顺序应用于请求，filter-name的值必须是部署描述符中的过滤器声明之一，可以使用url-pattern或servlet-name来指定匹配请求。
- filter-mapping 元素的结构
-
listener 元素
- 监听器表示应用程序监听器Bean的部署属性，子元素listener-class使用类，必须是已经注册为web应用程序监听器bean，该值是监听器类的完全限定的类名。
-
servlet 元素
- servlet用于声明servlet，它包含servlet的声明性数据，jsp-file元素包含以”/“开头的web应用程序JSP文件的完整路径，如果指定了一个jsp文件，并且存在load-on-startup元素，那么jsp文件就应该预编译并加载。servlet-name元素包含servlet的规范名称，每个servlet-name在web应用程序中都是唯一的，servlet-name元素内容不能为空，servlet-class含servlet的完全限定的类名。run-as元素指定用于执行组件的表示,它包含一个可选的description，以及有role-name元素指定的安全角色的名称。load-on-starup元素表明该servlet应该在web应用程序启动时被加载（实例化并调用init())。该元素的元素内容必须为整数，该整数表示应加载servlet的顺序。如果值为负数，或元素不存在，则容器可以随时选择加载servlet，如果值为正整数或0，则在部署应用程序时，容器必须加载并初始化servlet，容器必须保证整数越小加载顺序越先加载。容器可能选择servlet的load-on-startup的值进行确定加载顺序，security-role-ref元素在组件或部署组件的代码中声明安全角色引用。它由一个可选description，以及一个指向安全角色的可选链接（role-link)，如果这个安全角色未指定，则部署者必须选择适当的安全角色，可选的async-supported元素（如果指定）表示servlet可以支持异步请求处理，如果servlet支持文件上传功能并且处理mime-multipart请求，则可以通过描述符中的multipart-config元素提供其配置。multipart-config元素可以用于指定文件存储的位置，文件上传的大小限制，最大请求大小和写到磁盘的阈值大小。
- servlet元素结构
-
servlet-mapping元素
- servlet-mapping定义在一个servlet和url pattern之间的映射。
- servlet-mapping 元素结构
-
session-config 元素
- session-config定义此web应用程序的会话参数。子元素 session-timeout定义了此web应用程序中创建的所有会话的默认会话超时时间间隔，指定的超时必须以分钟为单位表示，如果超时时间为0 或更小，则容器确保会话的默认行为永远不会超时，如果未指定此元素，则容器必须设置其默认超时期限。
- session-config 元素结构
-
mime-mapping 元素
- mime-mapping 定义扩展名和mime 类型一个映射关系，extension元素包含描述扩展名的字符串，例如"txt"
- mime-mapping元素结构
-
welcome-file-list 元素
- welcome-file-list 包含一个欢迎文件的有序列表，子元素welcome-file包含用默认欢迎文件的文件名，例如index.html
- welcome-file-list 元素 结构
-
error-page 元素
- error-page 包含异常类型或错误码与web应用程序中资源路径之间的映射，但是可以省略error-code 或 exception-type元素以指定默认错误页面。子元素异常类型包含java的完全限定的类名。子元素localtion 包含web应用程序中资源相对于web应用程序根目录的位置，位置的值必须以"/"开头。
- error-page 元素结构
-
jsp-config 元素
- jsp-config 用于为web应用程序中的JSP文件提供全局配置信息，他有两个子元素，taglib和jsp-property-group. tablib元素可用于提供有关标记库的信息，该标记库由web应用程序中的jsp页面使用，有关详细信息，请参见JavaServlet Pages规范版本2.1.
- jsp-config元素结构
-
security-constraint元素
- security-constraint用于将安全约束与一个或多个web资源集合关联。子元素web-resource-collection标识资源的子集，并在适用于安全性约束的web应用程序中的那些资源上使用HTTP方法。auth-constraint表示应被允许访问此资源集合的用户角色。此处使用的role-name必须与此web应用程序定义的security-role元素之间的role-name相关联，或者必须是特殊保留的角色名称"*", 这是一个紧凑语法，用于表示在web应用程序中的所有角色。web应用程序，如果同时出现"*" 和 角色名称，则容器会将其解释为所有角色，如果未定义角色，则不允许任何用户访问web应用程序中包含安全性所描述的部分，确定访问权限是，容器会区分角色名称和大小写，user-data-constraint指示客户端之间的数据通信方式和容器应该使用transport-guarantee元素保护传输的内容，transport-guarantee枚举值是 NONE、INTEGRAL，CONFIDENTIAL
- security-constraint 元素结构
-
login-config 元素
- login-config用于配置应使用的身份验证方法，此应用程序应使用的领域名称以及表单登录机制所需的属性，子元素auth-method为web应用程序配置身份验证机制。元素内容必须BASIC， DIGEST， FORM，CLIENT-CERT或供应商提供验证方法。realm-name表示用于为web英速亚程序选择的身份验证方案的领域名称，form-login-config指定应在基于FORM的登录中使用的登录和错误页面，如果不使用基于FORM的登录名，则将忽略这些元素。
- login-config 元素结构
-
security-role 元素
- security-role定义一个安全角色，子元素角色名称指定安全角色的名称，该名称必须符合NMTOKEN的词汇规范。
- security-role 元素结构
-
env-entry 元素
- env-entry声明应用程序的环境变量键值对，它子元素env-entry-name 包含部署组件的环境变量键值对的名称，比如一个名称JNDI相对上下文信息"java:comp/env", 该名称在部署组件中必须是唯一的，env-entry-type 必须是全限定类名的环境变量键值对， 子元素env-entry-value指定部署组件的环境变量的值，该值必须是一个字符串，该字符串对于以单个String作为参数的指定类型的构造函数有效，或者对于java.lang.Character都是单个字符。可选的injection-target元素用于定义将命名资源注入到字段或JavaBean的属性中，injection-target指定一个类和该类中应向其中注入资源的名称，injection-target-class必须全限定的类名。首先将目标作为javabean属性名称查找，如果未找到，则将目标作为字段名称查找。通过调用目标属性的set方法或在名称中设置一个值，可以在类初始化期间将指定的资源注入到目标属性中。如果一个injection-target指定环境环境变量，这个env-entry-type 可能被忽略或必须匹配到注入的类型，如果injection-target没有指定，那么env-entry-type必须指定值。
- env-entry 元素结构
-
ejb-ref 元素
-
ejb-ref声明了对Enterprise Bean的主页的引用。ejb-ref-name指定引用企业Bean的部署组件的代码中使用名称。ejb-ref-type是引入的企业bean的预期类型， 可以是Entity或Session，home定义了所引用的企业bean的home接口的标准名称。远程定义引用的企业bean的远程接口的标准名称。ejb-link指定将EJB引用链接到企业bean。
-
ejb-ref 元素结构
-
-
-
ejb-local-ref 元素
- 这个ejb-local-ref声明引用这个企业bean的本地home，local-home 定义全限定的企业bean的接口。local定义全限定的企业bean的local接口
- ejb-local-ref 元素结构
-
service-ref 元素
- service-ref声明对Web service的引用，service-ref-name声明一个逻辑名称用于组件去查找这个web service，推荐所有服务引用名称都以/service/开头， service-interface 定义一个客户端依赖的JAX-WS全限定类名服务接口，在大多数情况下，这个值将是javax.xml.rpc.Service, JAX-WS生成服务接口类可能也被指定了，wsdl-file元素包含WSDL文件的urI路径。这个路径是相对根路径的，jaxrpc-mapping-file包含一个文件名称与java接口的映射JAX-WS关系，wsdl-file是描述WSDL文件，这个文件名称是一个相对于模块文件的路径。service-qname元素声明所引用的特定WSDL服务元素，如果未声明wsdl文件，则未指定， port-component-ref元素声明容器上的客户端依赖性，以将服务端点接口解析为WSDL端口。可以选择将服务端点接口与特定的端口组件相关联。这仅仅由容器用于Service.getPort(Class)方法调用。handler元素为端口组件声明处理程序。处理程序可以使用HandlerInfo接口访问init-param名称、键值对，如果未指定port-name,则假定处理程序与服务的所有端口相关联。有关详细信息，请求参见JSR-109规范，并非java ee实现的一部分的容器不需要支持此元素。
- service-ref 元素结构
-
resource-ref 元素
- resource-ref包含部署组件对外资源的引用的声明，res-ref-nam指定资源管理器连接工厂引用的名称，该名称是相对于java:comp/env 上下文的JNDI名称。该名称在部署文件中必须是唯一的，res-type元素指定数据源的类型，类型是标准java语言类或预期有数据源实现的接口。res-auth指定是部署组件代码以编程方式登录到资源管理器，还是容器是否代表部署组件登录到资源管理器。在后一种情况下，容器使用部署者提供的信息，res-sharing-scope指定是否可以共享通过给定资源管理器连接工厂引用获取的连接。该值（如果指定）必须为可共享或不可共享。可选的injection-target元素用于定义将命名资源注入到字段或javabeans属性中。
- resource-ref元素结构
-
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，在这种情况下，将使用目标的类型，如果两者都指定，则类型必须与注射目标的类型兼容。
- resource-env-ref 元素结构
-
message-destination-ref 元素
-
message-destination-ref元素包含对部署组件对于部署组件环境中的资源关联的消息目标的引用的声明。message-destination-ref-name元素指定消息目标引用的名称，它的值是部署组件代码中使用的环境变量名称。相对于java:comp/env上下文的JNDI名称。对于企业bean，在ejb-jar中必须是唯一的，对于其他bean，则是部署文件中的，message-destination-type指定目标的类型，类型由预期由目标实现的Java接口指定。消息目标用法指定了参考所指示的消息目标的用途。该值指示是否从消息模板消费消息，为目标产生消息，还是两者兼而有之，组装者利用此信息将目的地的生产者与其消费者联系起来。message-destination-link将消息模板引用或消息驱动的bean链接到达消息目标。组装者设置值是反应生产者和消费者之间消息流动关系。该值必须是同一部署文件中或同一java EE 应用程序单元中另一个部署文件中消息目的地的message-destination-name，可替换第，该值可以由路径名组成，该路径名指定包含锁引用的消息目的地部署文件，该目标消息的目的地的消息目的地名称由路径名称附加并以"#"分隔，路径名是相对于包含引用消息目标的部署组件的部署文件而言的。它允许唯一标识具体相同名称的多个消息目标，否则必须指定消息目标类型，这这种情况下，将使用目标的类型，如果两者都有指定，则类型必须与注册目标的类型兼容。
-
例子
-
<message-destination-ref> <message-desitnation-ref-name> jms/StockQueue </message-desitnation-ref-name> <message-destination-type> javax.jms.Queue </message-destination-type> <message-destination-usage> Comsumes </message-destination-usage> <message-destination-link> CorporateStocks </message-destination-link> </message-destination-ref>
-
-
message-destination-ref 元素结构
-
-
-
message-destination 元素
-
message-destination 指定消息的目的地，部署者将此元素描述的逻辑目标映射到物理目标，message-destination-name元素指定消息目标的名称，此名称在部署文件中的消息目标的名称中必须唯一。
-
例子
-
<message-destination> <message-destination-name> CorporateStocks </message-destination-name> </message-destination>
-
-
message-destination元素结构
-
-
-
locale-encoding-mapping-list 元素
- locale-encoding-mapping-list包含语言环境和编码之间的映射关系，由子元素locale-encoding-mapping指定。
- locale-encodingmapping-list 元素结构
##14.5、例子
- 以下示例说明了部署描述符架构中列出的定义的用法
14.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>这是简单例子</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>
14.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>这是安全应用配置</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>
1795
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
