Apache Tomcat 11 配置参考 (11.0.8) - GlobalNamingResources 组件

GlobalNamingResources 组件

简介

GlobalNamingResources 元素定义了 Server 的全局 JNDI 资源。

这些资源列在服务器的全局 JNDI 资源上下文中。此上下文与 JNDI 资源操作指南中描述的每个 Web 应用程序的 JNDI 上下文是不同的。此元素中定义的资源在每个 Web 应用程序的上下文中不可见，除非您使用 <ResourceLink> 元素明确地链接它们。

属性

嵌套组件

特殊功能

环境条目

您可以通过在此元素内部嵌套 <Environment> 条目，将命名值配置为作为环境条目资源对所有 Web 应用程序可见。例如，您可以像这样创建一个环境条目

<GlobalNamingResources ...>
  ...
  <Environment name="maxExemptions" value="10"
         type="java.lang.Integer" override="false"/>
  ...
</GlobalNamingResources>

这等效于在 Web 应用程序部署描述符 (/WEB-INF/web.xml) 中包含以下元素

<env-entry>
  <env-entry-name>maxExemptions</env-entry-name>
  <env-entry-value>10</env-entry-value>
  <env-entry-type>java.lang.Integer</env-entry-type>
</env-entry>

但是不需要修改部署描述符来定制此值。

<Environment> 元素的有效属性如下

属性	描述
`description`	可选，此环境条目的可读描述。
`name`	要创建的环境条目的名称，相对于 `java:comp/env` 上下文。
`override`	如果您不希望 Web 应用程序部署描述符中找到的具有相同环境条目名称的 `<env-entry>` 覆盖此处指定的值，请将其设置为 `false`。默认情况下，允许覆盖。
`type`	Web 应用程序对此环境条目期望的完全限定 Java 类名。必须是 Web 应用程序部署描述符中 `<env-entry-type>` 的合法值。
`value`	从 JNDI 上下文请求时将呈现给应用程序的参数值。此值必须可转换为 `type` 属性定义的 Java 类型。

资源定义

您可以通过在此元素中定义资源，然后使用 <Context> 元素中的 <ResourceLink> 元素链接它们，来声明 Web 应用程序部署描述符中 <resource-ref> 和 <resource-env-ref> 元素的 JNDI 查找要返回的资源的特性。您必须还要使用 Resource 元素上的属性定义任何其他所需参数，以配置要使用的对象工厂（如果 Tomcat 尚未知晓），以及用于配置该对象工厂的属性。

例如，您可以像这样创建一个资源定义

<GlobalNamingResources ...>
  ...
  <Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/>
  ...
</GlobalNamingResources>

这等效于在 Web 应用程序部署描述符 (/WEB-INF/web.xml) 中包含以下元素

<resource-ref>
  <description>Employees Database for HR Applications</description>
  <res-ref-name>jdbc/EmployeeDB</res-ref-name>
  <res-ref-type>javax.sql.DataSource</res-ref-type>
  <res-auth>Container</res-auth>
</resource-ref>

但是不需要修改部署描述符来定制此值。

<Resource> 元素的有效属性如下

属性	描述
`auth`	指定 Web 应用程序代码是编程方式登录到相应的资源管理器，还是容器代表应用程序登录到资源管理器。此属性的值必须是 `Application` 或 `Container`。如果 Web 应用程序将在 Web 应用程序部署描述符中使用 `<resource-ref>` 元素，则此属性是必需的，但如果应用程序改用 `<resource-env-ref>`，则此属性是可选的。
`closeMethod`	当单例资源不再需要时，要调用的零参数方法的名称。这旨在加速资源的清理，否则这些清理将作为垃圾回收的一部分发生。如果 `singleton` 属性为 false，则此属性将被忽略。如果未指定，则不定义默认值，并且不会调用 close 方法。对于 Apache Commons DBCP 2 和 Apache Tomcat JDBC 连接池，您可以使用 `closeMethod="close"`。请注意，Apache Commons DBCP 2 要求设置此项才能干净关闭。当使用默认的 Tomcat 连接池（基于 DBCP 2）时，除非明确将其设置为空字符串，否则 Tomcat 将自动设置此属性。
`description`	可选，此资源的可读描述。
`name`	要创建的资源的名称，相对于 `java:comp/env` 上下文。
`scope`	指定通过此资源管理器获得的连接是否可以共享。此属性的值必须是 `Shareable` 或 `Unshareable`。默认情况下，连接假定为可共享。
`singleton`	指定此资源定义是否适用于单例资源，即只有一个资源实例的资源。如果此属性为 `true`，则对此资源的多次 JNDI 查找将返回相同的对象。如果此属性为 `false`，则对此资源的多次 JNDI 查找将返回不同的对象。对于 `javax.sql.DataSource` 资源，此属性必须为 `true` 才能启用 DataSource 的 JMX 注册。此属性的值必须是 `true` 或 `false`。默认情况下，此属性为 `true`。
`type`	Web 应用程序对此资源执行查找时所期望的完全限定 Java 类名。

资源链接

使用 <ResourceLink> 元素将全局上下文中的资源链接到每个 Web 应用程序的上下文中。以下是一个示例，演示如何根据 JNDI 资源操作指南中的示例定义，使自定义工厂可用于应用程序。

<Context>
  <ResourceLink
    name="bean/MyBeanFactory"
    global="bean/MyBeanFactory"
    type="com.mycompany.MyBean"
  />
</Context>

事务

您可以声明要为 java:comp/UserTransaction 的 JNDI 查找返回的 UserTransaction 的特性。您必须定义一个对象工厂类来实例化此对象，以及作为 Transaction 元素属性所需的资源参数，以及用于配置该对象工厂的属性。

<Transaction> 元素的有效属性如下

属性	描述
`factory`	JNDI 对象工厂的类名。