weblogic.xml 部署描述符元素
?
weblogic.xml 部署描述符元素
本文档提供 WebLogic Server 特定的部署描述符 weblogic.xml 中的元素的完整参考。如果您的 Web 应用程序不包含 weblogic.xml 部署描述符，WebLogic Server 会自动选择部署描述符元素的默认值。要查看?weblogic.xml?的 Schema，请转至?http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd。
weblogic.xml路径：C:\Oracle\Middleware\wlserver_10.3\server\lib\consoleapp\consolehelp\WEB-INF
下列部分描述 weblogic.xml 部署描述符中根元素?<weblogic-web-app>?下可定义的复杂部署描述符元素：
?
description 元素是 Web 应用程序的文字描述。
?
weblogic-version?元素表示该 Web 应用程序（在根元素?<weblogic-web-app>下定义）即将部署至的 WebLogic Server 的版本。该元素仅表示版本信息，WebLogic Server并不使用该元素。
?
security-role-assignment?元素声明 Web 应用程序安全角色与 WebLogic Server中一个或多个委托人之间的映射，如以下示例所示。
<security-role-assignment><role-name>PayrollAdmin</role-name>
<principal-name>Tanya</principal-name>
<principal-name>Fred</principal-name>
<principal-name>system</principal-name>
</security-role-assignment>还可以使用它将给定角色标记为外部定义的角色，如以下示例所示：
<security-role-assignment><role-name>roleadmin</role-name>
<externally-defined/></security-role-assignment><security-role-assignment>?元素中，必须定义?<principal-name>?或?<externally-defined>。不能两者都忽略。下表描述可在?security-role-assignment元素中定义的元素。
可选
<role-name><principal-name><externally-defined>，则此元素必需。<principal-name>?元素向一个角色映射多个委托人。有关安全领域的详细信息，请参阅?确保 WebLogic 安全性。<externally-defined><principal-name>，则此元素必需。?
?
run-as-role-assignment 元素将 web.xml 中的 run-as 角色名（servlet 元素的子元素）映射为系统中的有效用户名。对于给定 servlet，该值将被 servlet-descriptor 中的 run-as-principal-name 元素替代。如果给定角色名中没有指定 run-as-role-assignment，则 Web 应用程序容器使用 security-role-assignment 中定义的第一个 principal-name。以下示例说明如何使用 run-as-role-assignment 元素。
<run-as-role-assignment>
<role-name>RunAsRoleName</role-name>
<run-as-principal-name>joe</run-as-principal-name>
</run-as-role-assignment>
下表描述可在?run-as-role-assignment元素中定义的元素。
可选
<role-name><run-as-principal-name>?
?
这个 weblogic.xml 部署描述符指 reference-descriptorGroup，它属于 weblogic-j2ee-xsd 文件的一部分。将使用 reference-descriptorGroup 的以下子元素
resource-descriptionresource-description?元素用于将服务器资源的 JNDI 名映射至 WebLogic Server 中的 EJB 资源引用。请参阅?resource-description。resource-env-descriptionresource-env-description?元素将?ejb-jar.xml?部署描述符中声明的?resource-env-ref?映射至其代表的服务器资源的 JNDI 名。请参阅?resource-env-description。service-reference-descriptionweblogic.xml 部署描述符。
resource-description?元素用于将服务器资源的 JNDI 名映射至 WebLogic Server 中的 EJB 资源引用。
下表描述可在?resource-description?元素中定义的元素。
可选
<res-ref-name><jndi-name>.
resource-env-description?元素将?ejb-jar.xml?部署描述符中声明的resource-env-ref?映射至其代表的服务器资源的 JNDI 名。
下表描述可在?resource-env-description?元素中定义的元素。
可选
<res-env-ref-name><jndi-name>.
下表描述可在?ejb-reference-description?元素中定义的元素。
可选
<ejb-ref-name><jndi-name>.
下表描述可在?service-reference-description?元素中定义的元素。
可选
<service-ref-name><wsdl-url>?
session-descriptor?元素定义 servlet 会话的参数。
timeout-secsweb.xml?中的?session-timeout?元素（分钟）替代。invalidation-interval-secs60sharing-enabledtrue，则 Web 应用程序能够共享 HTTP 会话。id-lengthcookies-enabledtruefalse?来禁用它们。您可能会关闭该选项以进行测试。cookie-nameJSESSIONIDJSESSIONID。可以将其设置为适用于您的应用程序的更具体的名称。cookie-path/（斜杠），浏览器会向 WebLogic Server 服务的所有 URL 发送 cookie。可以将该路径设置为限制性更强的映射，以便限制浏览器会向其发送 cookie 的请求 URL。cookie-domaincookie-domain?设置为?.mydomain.com?会向?*.mydomain.com?域中的所有服务器返回 cookie。*.com?或?*.net?是无效的。Cookie.setDomain()。cookie-commentcookie-securefalseurl-rewriting-enabled?元素。cookie-max-age-secspersistent-store-typememoryreplicated?- 与?memory?相同，但会话数据将在群集服务器之间复制。persistent-store-type。否则，memory?为默认值。file?- 使用基于文件的持久性（另请参阅?persistent-store-dir）。jdbc?- 使用数据库存储持久性会话。（另请参阅?persistent-store-pool。）persistent-store-cookie-nameWLCOOKIEWLCOOKIE?cookie 中带有会话状态，不应在 Web 应用程序之间共享。persistent-store-dirsession_dbpersistent-store-dir?下创建的文件来确定会话的大小。注意，每个会话的大小随序列化会话数据的大小变化而变化。<server-name>\data\store\default?目录中自动创建默认存储。但是，默认存储不能在群集服务器间共享。persistent-store-poolNonepersistent-store-tablewl_servlet_sessionspersistent-store-type?设置为 jdbc 时，此项才适用。persistent-store-table?元素。jdbc-connection-timeout-secsurl-rewriting-enabledfalse?时，WebLogic Server 会在下面的响应中添加如下头信息：encode-session-id-in-query-paramsfalsefalse。）runtime-main-attribute?
?
jsp-descriptor?元素指定 JSP 编译器的配置参数列表。下表描述可在?jsp-descriptor?元素中定义的元素。
可选
page-check-seconds1falsekeepgeneratedfalsetrue，否则编译完成后将删除所有中间 Java 文件。verbosetruetrue?时，将向浏览器、命令提示和 WebLogic Server 日志文件中输出调试信息。working-direncoding<%@ page contentType="text/html; charset=custom-encoding"%>package-prefixjsp_servlettruefalsejsp:param?标记的 name 特性中使用运行时表达式值。它默认设置为?false。?
?
auth-filter 元素指定身份验证筛选器 HttpServlet 类。
?
<container-descriptor>?元素指定影响 Web 应用程序行为的参数列表。
如果要求对从 servlet 或 JSP 转发的请求进行身份验证，请添加?<check-auth-on-forward/>?元素。如果不要求重新身份验证，请省略此标记.例如：
<container-descriptor>????<check-auth-on-forward/></container-descriptor>
<filter-dispatched-requests-enabled>?元素控制是否向已调度的请求应用筛选器。默认值为 false。
<filter-dispatched-requests-enabled>?元素默认为 true。
<redirect-with-absolute-url>?元素控制?javax.servlet.http.HttpServletResponse.SendRedirect()?方法是否使用相对或绝对 URL 进行重定向。如果您使用的是代理 HTTP 服务器，而且不希望该 URL 转换为非相对链接，请将该元素设置为?false。
默认行为是将 URL 转换为非相对链接。
重定向中使用的用户可读数据。
<index-directory-enabled> 元素控制在找不到合适的索引文件的情况下是否自动生成 HTML 目录列表。
默认值为?false（不生成目录）。值为?true?或?false。
<index-directory-sort-by> 元素定义 weblogic.servlet.FileServlet 生成的目录列表的排序顺序。有效的 sort-by 值为 NAME、LAST_MODIFIED 和 SIZE。默认 sort-by 值为 NAME。
<servlet-reload-check-secs> 元素定义 WebLogic Server 是否执行 servlet 检查以查看 servlet 是否已更改，如果已更改，是否重新加载。
控制台中指定的值将始终优先于手工指定的值。
使用 <resource-reload-check-secs> 元素针对 Web 应用程序范围内资源路径中发现的缓存资源执行元数据缓存。该参数标识 WebLogic Server 检查资源是否发生修改的频率，如果已修改，则重新加载。
通过管理控制台为此参数指定的值具有优先级。
<single-threaded-servlet-pool-size> 元素定义用于 SingleThreadMode 实例缓冲池的缓冲池的大小。默认值为 5。
如果将 <session-monitoring-enabled> 元素设置为 true，则允许为会话创建运行时 Mbean。如果设置为默认值 false，则不创建运行时 Mbean。控制台中指定的值优先于手工设置的值。
<save-sessions-enabled> 元素控制重新部署或取消部署期间是否清除会话数据。它影响内存会话和复制会话。将值设置为 true 表示保存会话数据。设置为 false 则表示重新部署或取消部署 Web 应用程序时将破坏会话数据。默认值为 false。
如果将 <prefer-web-inf-classes> 元素设置为 true，则将优先加载位于 Web 应用程序的 WEB-INF 目录中的类，然后再加载应用程序或系统类加载器中的类。默认值为 false。控制台中指定的值优先于手工设置的值。
<default-mime-type> 元素的默认值为 null。该元素允许用户为未映射扩展名的内容类型指定默认 mime 类型。
<client-cert-proxy-enabled> 元素的默认值为 true。设置为 true 时，WebLogic Server 会将标识证书从客户端传递至后端服务器。同时，将通知 WebLogic Server 是否允许或放弃传入的 WL-Proxy-Client-Cert 头。
代理服务器插件将每一标识证书在 WL-Proxy-Client-Cert 头中进行编码，然后将其传递至后端 WebLogic Server 实例。每一 WebLogic Server 实例从该头中获取证书信息，确保其来自于安全来源并使用该信息对用户进行身份验证。对于后台 WebLogic Server 实例，此参数必须设置为 true（在群集/服务器级别上或 Web 应用程序级别上）。
如果将该元素设置为 true，请使用 weblogic.security.net.ConnectionFilter 以确保每一 WebLogic Server 实例仅接受与正在运行代理服务器插件的计算机的连接。如果指定 true 却不使用连接筛选器，则将形成潜在的安全漏洞，因为 WL-Proxy-Client-Cert 头是可以被欺骗的。
<relogin-enabled> 元素是向后兼容的参数。如果用户已登录，并尝试访问其不具有访问权限的资源，则会发生“禁止”(403) 响应。
在 Web 应用程序的 web.xml 描述符中定义的 security-constraints 元素中，auth-constraint 元素指明允许访问该资源集合的用户角色。此处的 role-name = "*" 是一种简洁的语法，用于表示 Web 应用程序中的所有角色。在过去的版本中，role-name = "*" 被视为在领域中定义的所有用户/角色。
此 allow-all-roles 元素是向后兼容的开关，可以用于恢复原有行为。默认行为是允许 Web 应用程序中定义的所有角色。weblogic-xml 中指定的值优先于 WebAppContainerMBean 中定义的值。
在使用已隐式注册为默认 servlet 的 weblogic.servlet.FileServlet 来提供静态文件的过程中，如果要使用本地 I/O，请将 native-io-enabled 设置为 true。（默认值为 false。）native-io-enabled 元素仅适用于 Windows。
minimum-native-file-size 元素仅适用于 native-io-enabled 设置为 true 时。它设置使用本地 I/O 时的最小文件大小。如果要提供的文件大于此值，则使用本地 I/O。如果不设置此值，则所使用的默认值为 4K。
当 disable-implicit-servlet-mappings 标志设置为 true 时，Web 应用程序容器不创建内部 servlet（*.jsp 和 *.class 等）的隐式映射；仅使用默认 servlet 映射。关闭隐式 servlet 映射的一个典型使用情况是配置 HttpClusterServlet 或 HttpProxyServlet 时。
默认值为 false。
如果 optimistic-serialization 处于打开状态，并将请求发送到所有 Servlet 上下文中，WebLogic Server 在收到 getAttribute(name) 时将不对上下文和请求特性进行序列化-除序列化。
这意味着必须确保将 Web 应用程序公用特性的作用域设置为共同的父类加载器（以应用程序为作用域）；如果两个 Web 应用程序不属于同一应用程序，则将这些特性置于系统类路径中。
当 optimistic-serialization 处于关闭状态（默认值）时，WebLogic Server 将在 getAttribute(name) 时序列化-除序列化上下文和请求特性，以免可能引发 ClassCastExceptions。
也可以在?WebAppContainerMBean?的域级别中指定优化序列化值，这也适用于所有 Web 应用程序。如果在 weblogic.xml 中指定该值，则该值将替代域级别上的值。
默认值为 false。
可以通过监视 ID 标识 HTTP 会话。默认情况下，给定 HTTP 会话的监视 ID 是随机字符串，为确保安全，它并不同于会话 ID。可以在?weblogic.xml?部署描述符的 session-descriptor 中设置?monitoring-attribute-name?元素，然后将某会话特性设置为所定义的?monitoring-attribute-name，从而配置监视 ID。然后，该会话特性值的toString()?将用作监视 ID。
monitoring-attribute-name元素适用于标记不同会话的会话运行时信息。例如，如果您的“用户名”特性是唯一的，可以将其设置为“用户名”。
WebAppComponentRuntimeBean.getSessionIds()?方法返回具有该名称的会话特性值的数组。如果没有设置，则返回随机生成的字符串的数组。
?
<charset-params> 元素用于定义非 unicode 操作的代码集行为。例如：
<charset-params>
<input-charset>
<resource-path>/*</resource-path>
<java-charset-name>UTF-8</java-charset-name>
</input-charset>
</charset-params>
使用?<input-charset>?元素定义用于读取?GET?和?POST?数据的字符集。例如：
<input-charset>????<resource-path>/foo</resource-path>????<java-charset-name>SJIS</java-charset-name></input-charset>
有关详细信息，请参阅下表描述可在?<input-charset>?元素中定义的元素。
可选
<resource-path><java-charset-name>?指定的 Java 字符集。<java-charset-name>.
使用?<charset-mapping>?元素将 IANA 字符集名称映射至 Java 字符集名称。例如：
<charset-mapping>????<iana-charset-name>Shift-JIS</iana-charset-name>????<java-charset-name>SJIS</java-charset-name></charset-mapping>
有关详细信息，请参阅下表描述可在?<charset-mapping>?元素中定义的元素。
可选
<iana-charset-name><java-charset-name>?元素指定的 Java 字符集。<java-charset-name>.
?
使用 virtual-directory-mapping 元素指定文档根，取代某些特定请求（例如图像请求）的 Web 应用程序的默认文档根。一组 Web 应用程序的所有图像可以存储于一个位置上，不需要复制到使用这些图像的每个 Web 应用程序的文档根中。对于传入的请求，如果已经指定虚拟目录，则 servlet 容器将首先在该虚拟目录中搜索所请求的资源，然后再在 Web 应用程序的原始文档根下搜索。这定义了两个位置上具有同一文档时的搜索优先级。
示例：
<virtual-directory-mapping>?????<local-path>c:/usr/gifs</local-path>?????<url-pattern>/images/*</url-pattern>?????<url-pattern>*.jpg</url-pattern></virtual-directory-mapping><virtual-directory-mapping>?????<local-path>c:/usr/common_jsps.jar</local-path>?????<url-pattern>*.jsp</url-pattern></virtual-directory-mapping>下表描述可在 virtual-directory-mapping 元素中定义的元素。
可选
<local-path>WebLogic Server 的虚拟目录映射实现要求您的目录匹配该映射的 url 模式。图像示例要求您在 c:/usr/gifs/images 上创建名为 images 的目录。这允许 servlet 容器在 images 目录下找到适用于多个 Web 应用程序的图像。
?
使用该元素指定用于 URL 模式匹配的类。WebLogic Server 默认 URL 匹配映射类是基于 J2EE 标准的 weblogic.servlet.utils.URLMatchMap。WebLogic Server 中包含的另外一个实现是 SimpleApacheURLMatchMap，可以通过使用 url-match-map 元素将该实现用作插件。
SimpleApacheURLMatchMap 的规则：
如果将 *.jws 映射至 JWSServlet，则
http://foo.com/bar.jws/baz 将解析为路径信息为 baz 的 JWSServlet。
按照如下示例在 weblogic.xml 中配置要使用的 URLMatchMap：
<url-match-map>
weblogic.servlet.utils.SimpleApacheURLMatchMap
</url-match-map>
?
security-permission 元素根据安全策略文件语法指定单个安全权限。有关 Sun 的安全权限规范的实现，请参阅以下 URL：
http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax
放弃可选的 codebase 和 signedBy 子句。
例如：
<security-permission-spec>
?????grant { permission java.net.SocketPermission "*", "resolve" };</security-permission-spec>
其中：
permission java.net.SocketPermission 是权限类名。
"*" 表示目标名称。
resolve 表示操作。
?
context-root 元素定义该独立 Web 应用程序的上下文根。如果 Web 应用程序不是独立的，而属于某 EAR 的一部分，请在该 EAR 的 META-INF/application.xml 文件中指定上下文根。application.xml 中的 context-root 设置优先于 weblogic.xml 中的 context-root 设置。
注意，该 weblogic.xml 元素仅用于使用两阶段部署模型进行部署时。
确定 Web 应用程序的上下文根的优先级顺序如下：
- 注意：不能为 EAR 库中的各个 Web 应用程序分别设置 context-root 元素。只能针对 Web 应用程序库进行设置。
?
使用 wl-dispatch-policy 元素，通过标识执行队列名称，从而将 Web 应用程序分配至已配置的执行队列。可以使用 per-servlet-dispatch-policy 元素在单个 servlet 或 jsp 级别上替代该 Web 应用程序级别参数。
?
使用 servlet-descriptor 元素聚合 servlet 特定的元素。
下表描述可在 servlet-descriptor 元素中定义的元素。
可选
<servlet-name><run-as-principal-name><init-as-principal-name>init-as-principal-name，则容器将使用 run-as-principal-name 元素。<destroy-as-principal-name>destroy-as-principal-name，则容器将使用 run-as-principal-name 元素。<dispatch-policy>?
?
work-manager?元素是?<weblogic-web-app>?元素的子元素。可以在?work-manager?元素中定义下列元素。
可选
?
?
logging?元素是?<weblogic-web-app>?元素的子元素。可以在?logging?元素中定义下列元素。
可选
指定日志文件的名称。需要提供该文件名的完整地址。
指定是否为 ManagedConnectionFactory 或 ManagedConnection 设置了日志编写器。如果将此元素设置为 true，则从 ManagedConnectionFactory 或 ManagedConnection 中生成的输出将发送到由 log-filename 元素指定的文件。
如果不指定此值，则 WebLogic Server 将使用其定义的默认值。
值范围：true | false
值范围：true | false
?
?
library-ref 元素引用计划用作当前 Web 应用程序中的 Web 应用程序库的一个库模块。
示例：
<library-ref><library-name>WebAppLibraryFoo</library-name>
<specification-version>2.0</specification-version><implementation-version>8.1beta</implementation-version><exact-match>false</exact-match>
</library-ref>只有下列子元素与 Web 应用程序相关：?library-name、specification-version、implementation-version?以及 exact-match。
可以在?library-ref?元素中定义下列元素。
可选
library-namespecification-versionimplementation-version?
?
本版本中增添了若干向后兼容性标志，允许您恢复 WebLogic Server 9.0 之前的版本中所见的行为。有关这些标志的完整列表和描述，以及有关 Web 应用程序、JSP 和 Servlet 向后兼容性的所有信息，请参阅?Upgrading WebLogic Application Environments?中的?Compatibility with Previous Releases。
?
要在全局级别上配置 Web 容器，请使用 WebAppContainerMBean。有关 WebAppContainerMBean 特性以及如何使用它们为所有 Web 应用程序指定域范围内的默认值的信息，请参阅位于?http://e-docs.bea.com/wls/docs90/wlsmbeanref/mbeans/WebAppContainerMBean.html?的 WebAppContainerMBean。