web.xml-部署描述符元素.doc

web.xml 部署描述符元素
在每一个Web应用程序路径的WEB-INF\下和conf\下存在一个Web.xml配置文件，
用来设定Web应用程序的配置。在Web.xml中的设定非常多，
接下来分段来说明它的各项设定：

td是由Sun Microsystems公司所制定的，可以在下列的网址获得详细的信息：

下列部分描述根元素 下的 web.xml Schema 中定义的部署描述符元素。

context-param
description
display-name
distributable
ejb-ref
ejb-local-ref
env-entry
error-page
filter
filter-mapping
icon
listener
login-config
mime-mapping
resource-env-ref
resource-ref
security-constraint
security-role
Servlet
servlet-mapping
session-config
taglib
web-app
welcome-file-list

--------------------------------------------------------------------------------

icon
icon 元素指定用于在 GUI 工具中表示 Web 应用程序的大小图像在 Web 应用程序中的位置。（servlet 元素中也有一个名为 icon 的元素，用于提供在 GUI 工具中表示 servlet 的图标。）

下表描述可以在 icon 元素中定义的元素。

元素 必需/可选 描述
可选 用于在 GUI 工具中表示 Web 应用程序的 .gif 或 .jpg 小图像（16x16 像素）的位置。当前 WebLogic Server 尚不使用此元素。
可选 用于在 GUI 工具中表示 Web 应用程序的 .gif 或 .jpg 大图像（32x32 像素）的位置。当前 WebLogic Server 尚不使用此元素。

------------

display-name
可选的 display-name 元素指定 Web 应用程序的显示名称（可以由 GUI 工具显示的简短名称）。

元素 必需/可选 描述
可选 当前 WebLogic Server 尚不使用此元素。

--------------------------------------------------------------------------------

description
可选的 description 元素提供关于 Web 应用程序的描述性文本。

元素 必需/可选 描述
可选 当前 WebLogic Server 尚不使用此元素。

--------------------------------------------------------------------------------

distributable
WebLogic Server 不使用 distributable 元素。

元素 必需/可选 描述
可选 当前 WebLogic Server 尚不使用此元素。

--------------------------------------------------------------------------------

context-param
可选的 context-param 元素中包含 Web 应用程序的 Servlet 上下文初始化参数的声明。下表描述 Web 应用程序容器所使用的保留上下文参数，在weblogic.xml 中已不赞成使用这些参数，而提供了替换参数。

不赞成使用的参数 描述 weblogic.xml 中的替换元素weblogic.httpd.inputCharset 定义非 unicode 操作的代码集行为。 weblogic.xml 中的 input-charset（在 charset-param 内定义）。请参阅input-charset。
weblogic.httpd.servlet.reloadCheckSecs 定义 WebLogic Server 检查 servlet 是否发生修改的频率，如果已修改，则重新加载。值为 -1 则永不重新加载，值为 0 则始终重新加载。默认设置为 1 秒。 weblogic.xml 中的 servlet-reload-check-secs（在 container-descriptor 中定义）。

请参阅 container-descriptor。
weblogic.httpd.servlet.classpath 设置此值后，容器会将此路径追加到 Web 应用程序类路径上。不建议采用此方法，对于此方法的支持仅为向后兼容。 无替换。使用其他方法，例如清单类路径或 WEB-INF/lib 或 WEB-INF/classes 或虚拟目录。
weblogic.httpd.defaultServlet 设置 Web 应用程序的默认 servlet。不建议采用此方法，
对于此方法的支持仅为向后兼容。 无替换。而是使用 web.xml 中的 servlet 和 servlet-mapping 元素定义默认 servlet。默认 servlet 的 URL模式应该是“/”。请参阅 servlet-mapping。有关 servlet 映射的其他示例，请参阅 Servlet 映射。以下 context-param 参数仍有效。

元素 必需/可选 描述
weblogic.httpd.
clientCertProxy optional 此特性指定 Web 应用程序客户端的证书由代理插件或 HttpClusterServlet所发送的特殊WL-Proxy-Client-Cert 头提供。如果在代理服务器上执行用户身份验证，则此设置适用–设置clientCertProxy 会使代理服务器在特殊的头 WL-Proxy-Client-Cert中将证书传递给群集。
WL-Proxy-Client-Cert 头可以由能够访问 WebLogic Server 的任意客户端提供。WebLogic Server 从该头中获取证书信息，信任它来自安全来源（该插件）并使用该信息来对用户进行身份验证。
出于此原因，如果您设置 clientCertProxy，请使用连接筛选器确保 WebLogic Server 仅接受来自正在运行该插件的计算机的连接。
除为单个 Web 应用程序设置此特性外，您还可以定义此特性：
在管理控制台中的“服务器”-->“配置”-->“常规”页面上，为服务器示例承载的所有 Web 应用程序设置该特性在“群集”-->“配置”-->“常规”页面上，为群集中服务器实例所承载的所有 Web 应用程序设置该特性

--------------------------------------------------------------------------------

filter
filter 元素定义筛选器类及其初始化特性。有关筛选器的详细信息，请参阅配置筛选器。

下表描述可在 filter 元素中定义的元素。

元素 必需/可选 描述
可选 指定用于在 GUI 工具中表示筛选器的大小图像在 Web 应用程序中的位置。包含小图标和大图标元素。
当前 WebLogic Server 尚不使用此元素。
必需 定义筛选器的名称，用于在部署描述符中的其他位置上引用筛选器定义。
可选 希望由 GUI 工具显示的简短名称。
可选 筛选器的文字描述。
必需 筛选器的完全限定类名。
可选 包含名/值对并用作筛选器的初始化特性。
每个特性使用独立的一组 标记。

-----------------------------

filter-mapping
下表描述可在 filter-mapping元素中定义的元素。

元素 必需/可选 描述
必需 要将 URL 模式或 servlet 映射至的筛选器的名称。该名称对应于使用 元素在 元素中分配的名称。
必需 - 或由 映射 描述用于解析 URL 的模式。将 http://host:port/ + ContextPath 之后的 URL 部分与 WebLogic

Server 的 进行比较。如果模式匹配，则将调用该元素中映射的筛选器。
示例模式：
/soda/grape/*
/foo/*
/contents
*.foo
URL 必须遵循 Servlet 2.3 规范中指定的规则。
必需 - 或由 映射 Servlet 的名称，如果调用它，则会执行该筛选器。

----------------------------------------------------------------------------

listener
使用 listener 元素定义应用程序监听器。

元素 必需/可选 描述
可选 响应 Web 应用程序事件的类的名称。

有关详细信息，请参阅配置事件监听器类。

--------------------------------------------------------------------------------

servlet
servlet 元素中包含 servlet 的声明性数据。

如果指定了 jsp-file 且存在 元素，则将在 WebLogic Server 启动时预编译和加载该 JSP。

下表描述可在 servlet 元素中定义的元素。

元素 必需/可选 描述
可选 用于在 GUI 工具中表示 servlet 的大小图像在 Web 应用程序中的位置。包含小图标和大图标元素。
当前 WebLogic Server 尚不使用此元素。
必需 定义 servlet 的规范名称，用于在部署描述符中的其他位置上引用 servlet 定义。
可选 希望由 GUI 工具显示的简短名称。
可选 servlet 的文字描述。
必需（或使用 ） servlet 的完全限定类名。
在 servlet 正文中仅使用 标记或 标记中的任意一种。
必需（或使用 ） Web 应用程序中的 JSP 文件相对于 Web 应用程序根目录的完整路径。
在 servlet 正文中仅使用 标记或 标记中的任意一种。
可选 包含名/值对并用作 servlet 的初始化特性。
每个特性使用独立的一组 标记。
可选 当 WebLogic Server 启动时，WebLogic Server 将初始化此 servlet。此元素内容可选，但必须是正整数，它指明

servlet 的加载顺序。指定了低整数的 servlet 将于高整数 servlet 之前加载。如果没有指定任何值，或如果所指定的值不是正整数，则在应用程

序启动期间，WebLogic Server 可以以任意顺序加载 servlet。
可选 指定将用于 Web 应用程序执行的 run-as 标识。该元素包含可选描述和安全角色的名称。
可选 用于将 所定义的安全角色名链接到使用 Servlet 逻辑进行硬编码的备用角色名。使用此附加提取层，可以在部署时配置Servlet，且不必更改 Servlet 代码。

--------------------------------------------------------------------------------

icon
这是 Servlet 内的元素。

icon 元素指定用于在 GUI 工具中表示 servlet 的大小图像在 Web 应用程序中的位置。

下表描述可以在 icon 元素中定义的元素。

元素 必需/可选 描述
可选 指定用于在 GUI 工具中表示 servlet 的 .gif 或 .jpg 小图像（16x16 像素）在 Web 应用程序内的位置。
当前 WebLogic Server 尚不使用此元素。
可选 指定用于在 GUI 工具中表示 servlet 的 .gif 或 .jpg 小图像（32x32 像素）在 Web 应用程序内的位置。
当前 WebLogic Server 尚不使用此元素。

-------------

init-param
这是 Servlet 内的元素。

可选的 init-param元素中包含用作 servlet 的初始化特性的名/值对。每个特性使用独立的一组 init-param 标记。

您可以使用 javax.servlet.ServletConfig.getInitParameter() 方法访问这些特性。

下表描述可在 init-param元素中定义的元素。

元素 必需/可选 描述
必需 定义此特性的名称。
必需 为此特性定义一个 String 值。
可选 初始化特性的文字描述。

--------------------------------------------------------------------------------

security-role-ref
这是 Servlet 内的元素。

security-role-ref 元素将 定义的安全角色名链接到使用 Servlet 逻辑进行硬编码的备用角色名。使用此附加提取层，可以在部

署时配置 Servlet，且不必更改 Servlet 代码。

下表描述可在 security-role-ref元素中定义的元素。

元素 必需/可选 描述
可选 角色的文字描述。
必需 定义在 Servlet 代码中使用的安全角色或委托人的名称。
必需 定义稍后将在部署描述符中的 元素中定义的安全角色的名称。

-----------------------------------------------------------------------------

servlet-mapping
servlet-mapping 元素定义 servlet 和 URL 模式之间的映射。

下表描述可在 servlet-mapping元素中定义的元素。

元素 必需/可选 描述
必需 要将 URL 模式映射至的 servlet 的名称。该名称对应于您在 声明标记中为 servlet 分配的名称。
必需 描述用于解析 URL 的模式。将 http://host:port/ + WebAppName 之后的 URL 部分与 WebLogic Server 的 进

行比较。如果模式匹配，则将调用该元素中映射的 servlet。
示例模式：
/soda/grape/*
/foo/*
/contents
*.foo
URL 必须遵循 Servlet 2.3 规范中指定的规则。
有关 Servlet 映射的其他示例，请参阅 Servlet 映射。

--------------------------------------------------------------------------------

session-config
session-config 元素为此 Web 应用程序定义会话特性。

下表描述可在 session-config 元素中定义的元素。

元素 必需/可选 描述
可选 会话过期分钟数，该 Web 应用程序中的会话将在此时间后过期。除非输入此处列出的某个特殊值，否则此元素中设置的值

将替代 WebLogic 特定部署描述符 weblogic.xml 中的 元素的 TimeoutSecs 特性中设置的值。
默认值：-2
最大值：Integer.MAX_VALUE ?
特殊值：
-2 表示使用 weblogic.xml的 ssion-descriptor> 元素中的 TimeoutSecs 设置的值。
-1 表示会话永不超时。将忽略 weblogic.xml 的 元素中设置的值。
有关详细信息，请参阅 session-descriptor。

--------------------------------------------------------------------------------

mime-mapping
mime-mapping 元素定义扩展名和 mime 类型之间的映射。

下表描述可在 mime-mapping元素中定义的元素。

元素 必需/可选 描述
必需 描述扩展名的字符串，例如：txt。
必需 描述定义的 mime 类型的字符串，例如：text/plain。

--------------------------------------------------------------------------------

welcome-file-list
可选的 welcome-file-list 元素中包含 welcome-file 元素的有序列表。

当 URL 请求是一个目录名时，WebLogic Server 将提供此元素中指定的第一个文件。如果找不到该文件，则服务器会尝试列表中的下一个文件。

有关详细信息，请参阅配置欢迎文件。

下表描述可在 welcome-file-list 元素中定义的元素。

元素 必需/可选 描述
可选 用作默认欢迎文件的文件名，例如 index.html

--------------------------------------------------------------------------------

error-page
可选的 error-page 元素指定错误代码或异常类型与 Web 应用程序中资源路径之间的映射。

WebLogic Server 响应 HTTP 请求的过程中发生错误或由于 Java 异常而发生错误时，WebLogic Server 会返回一个 HTML 页面，其中显示 HTTP 错

误代码或包含 Java 错误信息的页面。可以定义显示自己的 HTML 页面，而不显示这些默认错误页面，或响应 Java 异常。

有关详细信息，请参阅自定义 HTTP 错误响应。

下表描述可以在 error-page 元素中定义的元素。

注意： 定义 或 ，但两者不能同时定义。
元素 必需/可选 描述
可选 有效的 HTTP 错误代码，例如 404。
可选 Java 异常类型的完全限定类名，例如 java.lang.string
必需 为响应错误而显示的资源的位置。例如，/myErrorPg.html。

--------------------------------------------------------------------------------

taglib
可选的 taglib 元素描述 JSP 标记库。

该元素将 JSP 标记库描述符（Tag Library Descriptor，简称 TLD）与 URI 模式关联起来。尽管您可以在相对于 WEB-INF 目录的 JSP 中指定 TLD，但部署您的 Web 应用程序时，您仍可以使用 标记配置 TLD。每个 TLD 使用独立的元素。

下表描述可在 taglib元素中定义的元素。

元素 必需/可选 描述
必需 给出相对于 Web 应用程序根目录的标记库描述符的文件名。将标记库描述符文件存储在 WEB-INF 目录下是一个好主意，这样可以避免通过 HTTP 请求公开提供该文件。
必需 描述相对于 web.xml 文档位置的 URI，标识 Web 应用程序中使用的标记库。
如果该 URI 匹配 JSP 页面上 taglib 指令中使用的 URI 字符串，则使用此 taglib。

--------------------------------------------------------------------------------

resource-env-ref
resource-env-ref 元素包含 Web 应用程序对 Web 应用程序环境中的资源所关联的受管理对象的引用的声明。它包括可选的描述、资源环境引用名，

还指明了 Web 应用程序代码所预期的资源环境引用类型。

例如：

jms/StockQueue javax.jms.Queue下表描述可在 resource-env-ref 元素中定义的元素。

元素 必需/可选 描述
可选 提供资源环境引用的描述。
必需 指定资源环境引用的名称；其值为 Web 应用程序代码中使用的环境条目名称。名称是相对于 java:comp/env 上下文的 JNDI 名称，该名称在 Web 应用程序中必须唯一。
必需 指定资源环境引用的类型。它是 Java 语言类或接口的完全限定名称。

--------------------------------------------------------------------------------

resource-ref
可选的 resource-ref 元素定义外部资源的引用查找名。这使得 servlet 代码能够通过“虚拟”名称查找资源，该虚拟名称将映射至部署时的实际位置。

使用独立的 元素定义每个外部资源名称。在 WebLogic 特定部署描述符 weblogic.xml 中，外部资源名称映射至部署时的资源实际位置名称。

下表描述可在 resource-ref元素中定义的元素。

元素 必需/可选 描述
可选 文字描述。
必需 JNDI 树中使用的资源的名称。Web 应用程序中的 Servlet 使用此名称查找资源引用。
必需 与引用名称相对应的资源的 Java 类型。使用 Java 类型的完整包名。
必需 用于控制资源安全登录。
如果设置为 APPLICATION，则表明应用程序组件代码将以编程方式执行资源登录。如果设置为 CONTAINER，则 WebLogic Server 将使用随 login-

config 元素建立的安全上下文。请参阅 login-config。
可选 指定是否可以共享通过给定资源管理器连接工厂引用获取的连接。
有效值：
Shareable（可共享）
Unshareable（不可共享）

-------------

security-constraint
security-constraint 元素定义对 元素所定义的资源集合的访问权限。

有关在 Web 应用程序中配置安全的详细说明和示例，请参阅“确保 WebLogic 资源安全”。另外，有关 WebLogic 安全的详细信息，请参阅WebLogic 安全性编程。

下表描述可在 security-constraint 元素中定义的元素。

元素 必需/可选 描述
必需 定义应用此安全约束的 Web 应用程序的组件。
可选 定义哪些组或委托人可以访问此安全约束内定义的 Web 资源集合。另请参阅 auth-constraint。
可选 定义客户端如何与服务器进行通信。
另请参阅 user-data-constraint

----------------------------------------------------------------------------
web-resource-collection
每个 元素必须具有一个或多个 元素。它们定义应用此安全约束的 Web 应用程序的区域。

这是 security-constraint 内的元素。

下表描述可在 web-resource-collection 元素中定义的元素。

元素 必需/可选 描述
必需 此 Web 资源集合的名称。
可选 此安全约束的文字描述。
rn> 可选 使用一个或多个 元素声明此安全约束将应用至的 URL 模式。如果您不使用其中至少一个元素，则 WebLogic Server 将忽略 。
可选 使用一个或多个 元素声明受身份验证约束的 HTTP 方法（通常是 GET 或 POST）。如果忽略 元素，则默认行为是向所有 HTTP 方法应用安全约束。

auth-constraint 这是 security-constraint 内的元素。

可选的 auth-constraint 元素定义哪些组或委托人有权访问在此安全约束中定义的 Web 资源集合。

下表描述可以在 auth-constraint 元素中定义的元素。

元素 必需/可选 描述
可选 此安全约束的文字描述。
可选 定义哪些安全角色可以访问在此安全约束中定义的资源。安全角色名映射至使用 security-role-ref 的委托人。请参阅 security-role-ref。

user-data-constraint 这是 security-constraint 内的元素。

user-data-constraint元素定义客户端如何与服务器进行通信。

下表描述可在 user-data-constraint元素中定义的元素。

元素 必需/可选 描述
可选 文字描述。
必需 指定客户端和服务器之间的通信。
当使用 INTEGRAL 或 CONFIDENTIAL 传输保证对用户进行身份验证时，WebLogic Server 会建立安全套接口层 (SSL) 连接。
值范围：
NONE- 应用程序不需要任何传输保证。
INTEGRAL- 应用程序要求数据在客户端和服务器之间传输的过程中不会被更改。
CONFIDENTIAL- 应用程序要求传输数据以防止其他实体观察到传输的内容。

--------------------------------------------------------------------------------

login-config
使用可选的 login-config 元素配置如何对用户进行身份验证；应用于此应用程序的领域名称；表单登录机制所需要的特性。

如果使用此元素，则用户必须经过身份验证才能访问受 Web 应用程序中所定义的 约束的所有资源。一旦通过身份验证，则可以授权用户访问具有访问权限的其他资源。

下表描述可在 login-config元素中定义的元素。

元素 必需/可选 描述
可选 指定用于对用户进行身份验证的方法。可能的值：
BASIC - 使用浏览器身份验证。（这是默认值。）
FORM - 使用用户编写的 HTML 表单。
CLIENT-CERT
注意： 您可以通过逗号分隔列表定义多个身份验证方法，以便提供应变机制。将按照在 auth-method 列表中定义值的顺序尝试进行身份验证。请参阅“WebLogic 安全性编程”中的为身份验证方法提供应变机制。

可选 对用户凭据进行身份验证时所引用的领域名称。如果忽略，则默认使用管理控制台中的“Web 应用程序”“配置”“其他”选项卡上的“身份验证领域名”字段中定义的领域。
注意： 元素不引用 WebLogic Server 内的系统安全领域。该元素定义 HTTP 基本身份验证中使用的领域名称。系统安全领域是在服务器上执行特定操作时将检查的安全信息的集合。servlet 安全领域是访问页面和使用基本身份验证时要检查的另外一组安全信息的集合。

可选 如果您在 FORM 中配置 ，请使用此元素。请参阅 form-login-config。

form-login-config
这是 login-config 内的元素。

如果您在 FORM 中配置 ，请使用 元素。

元素 必需/可选 描述
必需 相对于文档根目录的 Web 资源 URI，用于对用户进行身份验证。这可以是 HTML 页面、JSP 或 HTTP servlet，且必须返回

一个包含符合特定命名约定的、基于 FORM 的身份验证的 HTML 页面。
必需 相对于文档根目录的 Web 资源 URI，会将它发送给用户以响应失败的身份验证登录。

--------------------------------------------------------------------------------

security-role
下表描述可在 security-role元素中定义的元素。

元素 必需/可选 描述
可选 此安全角色的文字描述。
必需 角色名。此处使用的名称在 WebLogic 特定的部署描述符 weblogic.xml 中必须有对应的条目，该部署描述符将角色映射到安全领域中的委托人。有关详细信息，请参阅 security-role-assignment。

--------------------------------------------------------------------------------

env-entry
可选的 env-entry 元素声明用于应用程序的环境条目。每个环境条目使用独立的元素。

下表描述可以在 env-entry