web.xml详解

sunday_jia

1 定义头和根元素
    部署描述符文件就像所有XML文件一样，必须以一个XML头开始。这个头声明可以使用的XML版本并给出文件的字符编码。
    DOCYTPE声明必须立即出现在此头之后。这个声明告诉服务器适用的servlet规范的版本（如2.2或2.3）并指定管理此文件其余部分内容的语法的DTD(Document Type Definition，文档类型定义)。
    所有部署描述符文件的顶层（根）元素为web-app。请注意，XML元素不像HTML，他们是大小写敏感的。因此，web-App和WEB-APP都是不合法的，web-app必须用小写。
2 部署描述符文件内的元素次序
XML 元素不仅是大小写敏感的，而且它们还对出现在其他元素中的次序敏感。例如，XML头必须是文件中的第一项，DOCTYPE声明必须是第二项，而web- app元素必须是第三项。在web-app元素内，元素的次序也很重要。服务器不一定强制要求这种次序，但它们允许（实际上有些服务器就是这样做的）完全 拒绝执行含有次序不正确的元素的Web应用。这表示使用非标准元素次序的web.xml文件是不可移植的。
下面的列表给出了所有可直接出现在web-app元素内的合法元素所必需的次序。例如，此列表说明servlet元素必须出现在所有servlet-mapping元素之前。请注意，所有这些元素都是可选的。因此，可以省略掉某一元素，但不能把它放于不正确的位置。
l icon icon元素指出IDE和GUI工具用来表示Web应用的一个和两个图像文件的位置。
l display-name display-name元素提供GUI工具可能会用来标记这个特定的Web应用的一个名称。
l description description元素给出与此有关的说明性文本。
l context-param context-param元素声明应用范围内的初始化参数。
l filter 过滤器元素将一个名字与一个实现javax.servlet.Filter接口的类相关联。
l filter-mapping 一旦命名了一个过滤器，就要利用filter-mapping元素把它与一个或多个servlet或JSP页面相关联。
l listener servlet API的版本2.3增加了对事件监听程序的支持，事件监听程序在建立、修改和删除会话或servlet环境时得到通知。Listener元素指出事件监听程序类。
l servlet 在向servlet或JSP页面制定初始化参数或定制URL时，必须首先命名servlet或JSP页面。Servlet元素就是用来完成此项任务的。
l servlet-mapping 服务器一般为servlet提供一个缺省的URL：
http://host/webAppPrefix/servlet/ServletName
。但是，常常会更改这个URL，以便servlet可以访问初始化参数或更容易地处理相对URL。在更改缺省URL时，使用servlet-mapping元素。
l session-config 如果某个会话在一定时间内未被访问，服务器可以抛弃它以节省内存。可通过使用HttpSession的setMaxInactiveInterval方法 明确设置单个会话对象的超时值，或者可利用session-config元素制定缺省超时值。
l mime-mapping 如果Web应用具有想到特殊的文件，希望能保证给他们分配特定的MIME类型，则mime-mapping元素提供这种保证。
l welcom-file-list welcome-file-list元素指示服务器在收到引用一个目录名而不是文件名的URL时，使用哪个文件。
l error-page error-page元素使得在返回特定HTTP状态代码时，或者特定类型的异常被抛出时，能够制定将要显示的页面。
l taglib taglib元素对标记库描述符文件（Tag Libraryu Descriptor file）指定别名。此功能使你能够更改TLD文件的位置，而不用编辑使用这些文件的JSP页面。
l resource-env-ref resource-env-ref元素声明与资源相关的一个管理对象。
l resource-ref resource-ref元素声明一个资源工厂使用的外部资源。
l security-constraint security-constraint元素制定应该保护的URL。它与login-config元素联合使用
l login-config 用login-config元素来指定服务器应该怎样给试图访问受保护页面的用户授权。它与sercurity-constraint元素联合使用。
l security-role security-role元素给出安全角色的一个列表，这些角色将出现在servlet元素内的security-role-ref元素的role-name子元素中。分别地声明角色可使高级IDE处理安全信息更为容易。
l env-entry env-entry元素声明Web应用的环境项。
l ejb-ref ejb-ref元素声明一个EJB的主目录的引用。
l ejb-local-ref ejb-local-ref元素声明一个EJB的本地主目录的应用。
3 分配名称和定制的URL
在web.xml中完成的一个最常见的任务是对servlet或JSP页面给出名称和定制的URL。用servlet元素分配名称，使用servlet-mapping元素将定制的URL与刚分配的名称相关联。
3.1 分配名称
为 了提供初始化参数，对servlet或JSP页面定义一个定制URL或分配一个安全角色，必须首先给servlet或JSP页面一个名称。可通过 servlet元素分配一个名称。最常见的格式包括servlet-name和servlet-class子元素（在web-app元素内），如下所示：
Test
moreservlets.TestServlet

这 表示位于WEB-INF/classes/moreservlets/TestServlet的servlet已经得到了注册名Test。给 servlet一个名称具有两个主要的含义。首先，初始化参数、定制的URL模式以及其他定制通过此注册名而不是类名引用此servlet。其次,可在 URL而不是类名中使用此名称。因此，利用刚才给出的定义，URL
http://host/webAppPrefix/servlet/Test
可用于
http://host/webAppPrefix/servlet/moreservlets.TestServlet
的场所。
3.2 定义定制的URL
大多数服务器具有一个缺省的serlvet URL：
http://host/webAppPrefix/servlet/packageName.ServletName
。 虽然在开发中使用这个URL很方便，但是我们常常会希望另一个URL用于部署。例如，可能会需要一个出现在Web应用顶层的URL（如，http: //host/webAppPrefix/Anyname），并且在此URL中没有servlet项。位于顶层的URL简化了相对URL的使用。此外，对 许多开发人员来说，顶层URL看上去比更长更麻烦的缺省URL更简短。
事实上，有时需要使用定制的URL。比如，你可能想关闭缺省URL映射，以便更好地强制实施安全限制或防止用户意外地访问无初始化参数的servlet。如果你禁止了缺省的URL，那么你怎样访问servlet呢？这时只有使用定制的URL了。
为 了分配一个定制的URL，可使用servlet-mapping元素及其servlet-name和url-pattern子元素。Servlet- name元素提供了一个任意名称，可利用此名称引用相应的servlet；url-pattern描述了相对于Web应用的根目录的URL。url- pattern元素的值必须以斜杠（/）起始。
下面给出一个简单的web.xml摘录，它允许使用URL
http://host/webAppPrefix/UrlTest
而不是
http://host/webAppPrefix/servlet/Test
或
http: //host/webAppPrefix/servlet/moreservlets.TestServlet。请注意，仍然需要XML头、 DOCTYPE声明以及web-app封闭元素。此外，可回忆一下，XML元素出现地次序不是随意的。特别是，需要把所有servlet元素放在所有 servlet-mapping元素之前。
Test
moreservlets.TestServlet
Test
/UrlTest
URL模式还可以包含通配符。例如，下面的小程序指示服务器发送所有以Web应用的URL前缀开始，以..asp结束的请求到名为BashMS的servlet。
BashMS
msUtils.ASPTranslator
BashMS
/*.asp
3.3 命名JSP页面
因为JSP页面要转换成sevlet，自然希望就像命名servlet一样命名 JSP页面。毕竟，JSP页面可能会从初始化参数、安全设置或定制的URL中受益，正如普通的serlvet那样。
部署描述符实际上是一个XML文件，包含了很多描述servlet/JSP应用的各个方面的元素，如servlet注册、servlet映射以及监听器注册。部署描述符从下面的XML头开始：

这个头指定了XML的版本号以及所使用的编码。头的下面是DOCTYPE声明：

这段代码指定文件类型定义(DTD)，可以通过它检查XML文档的有效性。下面显示的元素有几个特性，这些特性告诉我们关于DTD的信息：
●        web-app定义该文档(部署描述符，不是DTD文件)的根元素
●        PUBLIC意味着DTD文件可以被公开使用
●       "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"意味着DTD由Sun Microsystems, Inc.维护。
   该信息也表示它描述的文档类型是DTD Web Application 2.3，而且DTD是用英文书写的。
●        URL"
http://java.sun.com/dtd/web-app_2_3.dtd
"表示D文件的位置。
注意：
在部署描述符中， 用于注释。
部署描述符的根元素是web-app。DTD文件规定，web-app元素的子元素的语法如下：

正如您所看到的，这个元素含有23个子元素，而且子元素都是可选的。问号(？)表示子元素是可选的，而且只能出现一次。星号(*)表示子元素可在部署描述符中出现零次或多次。有些子元素还可以有它们自己的子元素。
web.xml文件中web-app元素声明的是下面每个子元素的声明。下面的章节讲述部署描述符中可能包含的所有子元素。
注意：
在Servlet 2.3中，子元素必须按照DTD文件语法描述中指定的顺序出现。比如，如果部署描述符中的web-app元素有servlet和servlet-mapping两个子元素，则servlet子元素必须出现在servlet-mapping子元素之前。在Servlet 2.4中，顺序并不重要。
下面对web.xml文件各元素进行详解
1. icon元素
icon元素用来指定GIF格式或JPEG格式的小图标(16×16)或大图标(32×32)的文件名。



icon元素包括两个可选的子元素：small-icon子元素和large-icon子元素。文件名是Web应用归档文件(WAR)的根的相对路径。
部署描述符并没有使用icon元素。但是，如果使用XML工具编辑部署描述符，XML编辑器可以使用icon元素。
2. display-name元素
如果使用工具编辑部署描述符，display-name元素包含的就是XML编辑器显示的名称。

下面是一个含有display-name元素的部署描述符：



Online Store Application

3. description元素
可以使用description元素来提供有关部署描述符的信息。XML编辑器可以使用description元素的值。

4. distributable元素
可以使用distributable元素来告诉servlet/JSP容器，编写将在分布式Web容器中部署的应用：

例如，下面是一个含有distributable元素的部署描述符的例子：





5. context-param元素
context-param元素含有一对参数名和参数值，用作应用的servlet上下文初始化参数。参数名在整个Web应用中必须是惟一的。




param-name 子元素包含有参数名，而param-value子元素包含的是参数值。作为选择，可用description子元素来描述参数。
下面是一个含有context-param元素的有效部署描述符：




jdbcDriver
com.mysql.jdbc.Driver


6. filter元素
filter元素用于指定Web容器中的过滤器。在请求和响应对象被servlet处理之前或之后，可以使用过滤器对这两个对象进行操作。利用下一节介绍的filter-mapping元素，过滤器被映射到一个servlet或一个URL模式。这个过滤器的filter元素和filter-mapping元素必须具有相同的名称。



icon、display-name和description元素的用法和上一节介绍的用法相同。init-param元素与context-param元素具有相同的元素描述符。filter-name元素用来定义过滤器的名称，该名称在整个应用中都必须是惟一的。filter-class元素指定过滤器类的完全限定的名称。
下面是一个使用filter元素的部署描述符的例子：




Encryption Filter
com.branysoftware.EncryptionFilter


7. filter-mapping元素
filter-mapping元素用来声明Web应用中的过滤器映射。过滤器可被映射到一个servlet或一个URL模式。将过滤器映射到一个servlet中会造成过滤器作用于servlet上。将过滤器映射到一个URL模式中则可以将过滤器应用于任何资源，只要该资源的URL与URL模式匹配。过滤是按照部署描述符的filter-mapping元素出现的顺序执行的。




filter-name值必须对应filter元素中声明的其中一个过滤器名称。下面是一个含有filter-mapping元素的部署描述符：




Encryption Filter
com.brainysoftware.EncryptionFilter


Encryption Filter
EncryptionFilteredServlet


8. listener元素
listener元素用来注册一个监听器类，可以在Web应用中包含该类。使用listener元素，可以收到事件什么时候发生以及用什么作为响应的通知。


下面是一个含有listener元素的有效部署描述符：




MyAppListener


9. servlet元素
servlet元素用来声明一个servlet。








icon、display-name和description元素的用法和上一节介绍的用法相同。init-param元素与context-param元素具有相同的元素描述符。可以使用init-param子元素将初始化参数名和参数值传递给servlet。
(1) servlet-name、servlet-class和jsp-file元素
servlet元素必须含有servlet-name元素和servlet-class元素，或者servlet-name元素和jsp-file元素。描述如下：
●        servlet-name元素用来定义servlet的名称，该名称在整个应用中必须是惟一的。
●        servlet-class元素用来指定servlet的完全限定的名称。
●        jsp-file元素用来指定应用中JSP文件的完整路径。这个完整路径必须由a/开始。
(2) load-on-startup元素
当启动Web容器时，用load-on-startup元素自动将servlet加入内存。加载servlet就意味着实例化这个servlet，并调用它的init方法。可以使用这个元素来避免第一个servlet请求的响应因为servlet载入内存所导致的任何延迟。如果load-on-startup元素存在，而且也指定了jsp-file元素，则JSP文件会被重新编译成servlet，同时产生的servlet也被载入内存。
load-on-startup元素的内容可以为空，或者是一个整数。这个值表示由Web容器载入内存的顺序。举个例子，如果有两个servlet元素都含有load-on-startup子元素，则load-on-startup子元素值较小的servlet将先被加载。如果load-on-startup子元素值为空或负值，则由Web容器决定什么时候加载servlet。如果两个servlet的load-on-startup子元素值相同，则由Web容器决定先加载哪一个servlet。
(3) run-as元素
如果定义了run-as元素，它会重写用于调用Web应用中servlet所设定的Enterprise JavaBean(EJB)的安全身份。Role-name是为当前Web应用定义的一个安全角色的名称。
(4) security-role-ref元素
security-role-ref元素定义一个映射，该映射在servlet中用isUserInRole (String name)调用的角色名与为Web应用定义的安全角色名之间进行。security-role-ref元素的描述如下：




role-link元素用来将安全角色引用链接到已定义的安全角色。role-link元素必须含有已经在security-role元素中定义的一个安全角色的名称。
(5) Faces Servlet的servlet元素
在 JSF应用中，需要为Faces Servlet定义一个servlet元素，如下所示：





Faces Servlet
javax.faces.webapp.FacesServlet
1  



Faces Servlet
/faces/*


10. seervlet-mapping 元素
seervlet-mapping 元素将URL模式映射到某个servlet。



在前面的“servlet元素”一节中已经介绍了使用servlet-mapping元素的例子。
11. session-config元素
session-config元素为Web应用中的javax.servlet.http.HttpSession对象定义参数。


session-timeout元素用来指定默认的会话超时时间间隔，以分钟为单位。该元素值必须为整数。如果session-timeout元素的值为零或负数，则表示会话将永远不会超时。
下面是一个部署描述符，在用户最近访问HttpSession对象30分钟后，HttpSession对象默认为无效：




30


12. mime-mapping元素
mime-mapping元素将mime类型映射到扩展名。



extension元素用来描述扩展名。mime-type元素则为MIME类型。
举个例子，下面的部署描述符将扩展名txt映射为text/plain：




txt
text/plain


13. welcome-file-list元素
当用户在浏览器中输入的URL不包含某个servlet名或JSP页面时，welcome-file-list元素可指定显示的默认文件。


举个例子说明，假设用户在浏览器的地址框中输入
http://www.mycompany.com/appName/
等地址。如果在Web应用的部署描述符中指定welcome-file-list元素，用户就会看到一个权限错误消息，或者是应用目录下的文件和目录列表。如果定义了welcome-file-list元素，用户就能看到由该元素指定的具体文件。
welcome-file子元素用于指定默认文件的名称。welcome-file-list元素可以包含一个或多个welcome-file子元素。如果在第一个welcome-file元素中没有找到指定的文件，Web容器就会尝试显示第二个，以此类推。
下面是一个包含welcome-file-list元素的部署描述符。该元素包含两个welcome-file元素：第一个指定应用目录中的main.html文件，第二个定义jsp目录下的welcom.jsp文件，jsp目录也在应用目录下。




main.html
jsp/welcome.jsp


如果用户键入的URL不包含servlet名称、JSP页面或其他资源，则不会在应用目录中找到main.html文件，这时就会显示jsp目录下的welcome.jsp文件。
14. error-page元素
error-page元素用于将一段错误代码或一个异常类型映射到Web应用中的资源路径，从而在产生特殊的HTTP错误或指定的Java异常时，将显示相关的资源。




error-code元素包含HTTP错误代码。exception-type是Java异常类型的完全限定的名称。location元素是Web应用中的资源相对于应用目录的路径。location的值必须从a/开始。
举个例子，每次产生HTTP 404错误代码时，下面的部署描述符可使Web容器显示error404.html页面：




404
/error404.html


15. taglib元素
taglib元素描述JSP定制标记库。



taglib-uri元素是用于Web应用中的标记库的URI。taglib-uri元素的值与WEB-INF目录相对应。
taglib-location元素包含一个位置，其中可以找到标记库的标记库描述符(TLD)文件。
16. resource-env-ref元素
可以使用resource-env-ref元素来指定对管理对象的servlet引用的声明，该对象与servlet环境中的资源相关联。



resource-env-ref-name元素是资源环境引用的名称，其值为servlet代码中使用的环境的入口名称。该名称是一个与java:comp/env相对应的Java命名和目录接口(JNDI)名称，该名称在整个Web应用中必须是惟一的。
17. resource-ref元素
resource-ref元素用于指定对外部资源的servlet引用的声明。






resource-ref子元素的描述如下：
●        res-ref-name是资源工厂引用名的名称。该名称是一个与java:comp/env上下文相对应的JNDI名称，并且在整个Web应用中必须是惟一的。
●        res-auth表明：servlet代码通过编程注册到资源管理器，或者是容器将代表servlet注册到资源管理器。该元素的值必须为Application或Container。
●        res-sharing-scope表明：是否可以共享通过给定资源管理器连接工厂引用获得的连接。该元素的值必须为Shareable(默认值)或Unshareable。
18. security-constraint元素
部署描述符中的security-constraint元素允许不通过编程就可以限制对某个资源的访问。





(1) web-resource-collection元素
web-resource-collection元素标识需要限制访问的资源子集。在web-resource-collection元素中，可以定义URL模式和HTTP方法。如果不存在HTTP方法，就将安全约束应用于所有的方法。





web-resource-name是与受保护资源相关联的名称。http-method元素可被赋予一个HTTP方法，比如GET和POST。
(2) auth-constraint元素
auth-constraint元素用于指定可以访问该资源集合的用户角色。如果没有指定auth-constraint元素，就将安全约束应用于所有角色。



role-name元素包含安全角色的名称。
(3) user-data-constraint元素
user-data-constraint元素用来显示怎样保护在客户端和Web容器之间传递的数据。



transport-guarantee元素必须具有如下的某个值：
●        NONE，这意味着应用不需要传输保证。
●        INTEGRAL，意味着服务器和客户端之间的数据必须以某种方式发送，而且在传送中不能改变。
●        CONFIDENTIAL，这意味着传输的数据必须是加密的数据。
在大多数情况下，安全套接字层(SSL)用于INTEGRAL或CONFIDENTIAL。
19. login-config元素
login-config元素用来指定所使用的验证方法、领域名和表单验证机制所需的特性。




login-config子元素的描述如下：
●        auth-method指定验证方法。它的值为下面的一个：BASIC、DIGEST、FORM或 CLIENT-CERT
●        realm-name指定HTTP Basic验证中使用的领域名。
●        form-login-config指定基于表单的登录中应该使用的登录页面和出错页面。如果没有使用基于表单的验证，则忽略这些元素。这个元素的定义如下，其中form-login-page用于指定显示登录页面的资源路径， form-error-page则用于指定用户登录失败时显示出错页面的资源路径。这两个页面路径都必须以a/开始，并与应用目录相对应。



20. security-role元素
security-role元素指定用于安全约束中的安全角色的声明。



21. env-entry元素
env-entry元素用于指定应用环境入口。





env-entry-name元素包含Web应用环境入口的名称。该名称是一个与java:comp/env相对应的JNDI名称，并且在整个应用中必须是惟一的。
env-entry-value元素包含Web应用环境入口的值。该值必须是一个字符串类型的值，并且对于指定类型的构造函数是有效的，该函数获得一个String参数；或者对于java.lang.Character是有效的，java.lang.Character对象是一个字符。
env-entry-type元素包含环境入口值的完全限定的Java类型，该环境入口值是Web应用代码所期望的。这个env-entry-type元素的值必须是如下之一：
java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.String
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double
22. ejb-ref元素
ejb-ref元素用于指定EJB的home接口的引用。







ejb-ref-name包含EJB引用的名称。EJB引用是servlet环境中的一个入口，它与java:comp/env相对应。这个名称在Web应用中必须是惟一的。为求一致性，推荐您的ejb-ref-name元素名称以ejb/开始。
ejb-ref-name元素包含引用的EJB的期望类型。这个值必须是Entity或Session。
home元素包含EJB的home接口的完全限定的名称。remote元素包含EJB的remote接口的完全限定的名称。
ejb-ref或ejb-local-ref元素中用到的ejb-link元素可指定EJB 引用被链接到另一个EJB。Ejb-link元素的值必须是同一个J2EE应用单元中某个EJB的ejb-name。Ejb-link元素中的名称可以由指定ejb-jar的路径名组成，该ejb-jar包含引用的EJB。目标bean的名称添加在后面，用字符a# 与路径名分隔。路径名与包含引用EJB的Web应用的WAR相对应。这就允许我们惟一标识具有相同ejb-name的多个企业bean。
23. ejb-local-ref元素
ejb-local-ref元素用于声明对EJB的本地home的引用。







local元素包含EJB本地接口的完全限定的名称。Local-home元素包含EJB本地home接口的完全限定的名称。


本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u2/69320/showart_2148580.html