web server apache tomcat11-08-JNDI Resources

前言

整理这个官方翻译的系列，原因是网上大部分的 tomcat 版本比较旧，此版本为 v11 最新的版本。

开源项目

从零手写实现 tomcat minicat 别称【嗅虎】心有猛虎，轻嗅蔷薇。

系列文章

web server apache tomcat11-01-官方文档入门介绍

web server apache tomcat11-02-setup 启动

web server apache tomcat11-03-deploy 如何部署

web server apache tomcat11-04-manager 如何管理？

web server apache tomcat11-06-Host Manager App -- Text Interface

web server apache tomcat11-07-Realm Configuration

web server apache tomcat11-08-JNDI Resources

web server apache tomcat11-09-JNDI Datasource

web server apache tomcat11-10-Class Loader

...

介绍

Tomcat为每个在其下运行的Web应用程序提供了一个JNDI InitialContext实现实例，以与Jakarta EE应用程序服务器提供的实例兼容。Jakarta EE标准在/WEB-INF/web.xml文件中提供了一组标准元素，用于引用/定义资源。

有关JNDI的编程API和Jakarta EE服务器支持的功能的更多信息，请参见以下规范，Tomcat模拟了它提供的服务：

Java命名和目录接口（从JDK 1.4开始包含）
Jakarta EE平台规范（特别是，请参见命名章节） web.xml配置以下元素可用于Web应用程序部署描述符（/WEB-INF/web.xml）中，以定义资源：
<env-entry> - 环境条目，一个单值参数，可用于配置应用程序的操作方式。
<resource-ref> - 资源引用，通常是指用于资源的对象工厂，例如JDBC DataSource、Jakarta Mail Session或配置到Tomcat中的自定义对象工厂。
<resource-env-ref> - 资源环境引用，Servlet 2.4中新增的一种资源引用变体，用于简化对不需要身份验证信息的资源的配置。只要Tomcat能够识别一个适当的资源工厂来创建资源，并且不需要进一步的配置信息，Tomcat就会使用/WEB-INF/web.xml中的信息来创建资源。

Tomcat提供了一些针对JNDI资源的特定于Tomcat的选项，这些选项无法在web.xml中指定。这些选项包括closeMethod，它可以在Web应用程序停止时更快地清理JNDI资源，以及singleton，它控制是否为每个JNDI查找创建资源的新实例。要使用这些配置选项，资源必须在Web应用程序的<Context>元素或$CATALINA_BASE/conf/server.xml中的<GlobalNamingResources>元素中指定。

context.xml配置如果Tomcat无法识别适当的资源工厂和/或需要额外的配置信息，则必须在Tomcat能够创建资源之前指定额外的Tomcat特定配置。Tomcat特定的资源配置输入在<Context>元素中，该元素可以在$CATALINA_BASE/conf/server.xml或最好是每个Web应用程序的上下文XML文件（META-INF/context.xml）中指定。

使用以下元素在<Context>元素中执行Tomcat特定的资源配置：

<Environment> - 配置标量环境条目的名称和值，这些环境条目将通过JNDI InitialContext公开给Web应用程序（相当于在Web应用程序部署描述符中包含<env-entry>元素）。
<Resource> - 配置资源的名称和数据类型，该资源可供应用程序使用（相当于在Web应用程序部署描述符中包含<resource-ref>元素）。
<ResourceLink> - 向全局JNDI上下文中定义的资源添加链接。使用资源链接使Web应用程序可以访问在<Server>元素的<GlobalNamingResources>子元素中定义的资源。
<Transaction> - 添加用于实例化可在java:comp/UserTransaction处可用的UserTransaction对象实例的资源工厂。可以将任意数量的这些元素嵌套在一个<Context>元素内，并且只与该特定Web应用程序相关联。

如果在<Context>元素中定义了资源，那么不需要在/WEB-INF/web.xml中定义该资源。但是，建议在/WEB-INF/web.xml中保留条目，以记录Web应用程序的资源需求。

如果对于在Web应用程序部署描述符（/WEB-INF/web.xml）中包含的<env-entry>元素和在Web应用程序的<Context>元素的一部分中的<Environment>元素都定义了相同的资源名称，则仅当相应的<Environment>元素允许时（通过将override属性设置为“true”），部署描述符中的值将优先。

全局配置 Tomcat维护服务器的全局资源的单独命名空间。这些在$CATALINA_BASE/conf/server.xml的<GlobalNamingResources>元素中配置。您可以通过使用<ResourceLink>将这些资源暴露给Web应用程序，以将其包含在每个Web应用程序的上下文中。

如果使用<ResourceLink>定义了资源，那么不需要在/WEB-INF/web.xml中定义该资源。但是，建议在/WEB-INF/web.xml中保留条目，以记录Web应用程序的资源需求。

使用资源在Web应用程序最初部署时，InitialContext被配置，并且被提供给Web应用程序组件（用于只读访问）。所有配置的条目和资源都放置在JNDI命名空间的java:comp/env部分中，因此对于资源的典型访问 - 在本例中是对JDBC DataSource的访问 - 看起来像这样：

java">// 获取我们的环境命名上下文
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");// 查找我们的数据源
DataSource ds = (DataSource)envCtx.lookup("jdbc/EmployeeDB");// 从池中分配并使用连接
Connection conn = ds.getConnection();
... 使用此连接访问数据库 ...
conn.close();

Tomcat标准资源工厂 Tomcat包含一系列标准资源工厂，可以为您的Web应用程序提供服务，并通过元素提供配置灵活性，而无需修改Web应用程序或部署描述符。以下各小节详细介绍了标准资源工厂的配置和用法。

有关如何创建、安装、配置和使用自定义资源工厂类的信息，请参阅添加自定义资源工厂。

注意 - 在标准资源工厂中，只有“JDBC数据源”和“用户事务”工厂被要求在其他平台上可用，并且只有在平台实现了Jakarta EE规范时才需要。所有其他标准资源工厂以及您自己编写的自定义资源工厂都特定于Tomcat，并且不能假定它们在其他容器上可用。

通用JavaBean资源 0. 介绍此资源工厂可用于创建符合标准JavaBeans命名约定的任何Java类的对象（即具有零参数构造函数，并且具有符合setFoo()命名模式的属性设置器）。如果工厂的singleton属性设置为false，则该资源工厂仅在每次查找此条目时创建适当的bean类的新实例。

使用此设施的步骤如下所述。

创建您的JavaBean类创建每次资源工厂被查找时将实例化的JavaBean类。例如，假设您创建了一个名为com.mycompany.MyBean的类，其代码如下所示：

java">package com.mycompany;public class MyBean {private String foo = "Default Foo";public String getFoo() {return (this.foo);}public void setFoo(String foo) {this.foo = foo;}private int bar = 0;public int getBar() {return (this.bar);}public void setBar(int bar) {this.bar = bar;}
}

声明您的资源需求然后，修改您的Web应用程序部署描述符（/WEB-INF/web.xml）以声明您将请求此bean的新实例的JNDI名称。最简单的方法是使用元素，例如：

<resource-env-ref><description>MyBean实例的对象工厂。</description><resource-env-ref-name>bean/MyBeanFactory</resource-env-ref-name><resource-env-ref-type>com.mycompany.MyBean</resource-env-ref-type>
</resource-env-ref>

警告 - 请确保您遵循Web应用程序部署描述符的DTD所要求的元素顺序！有关详细信息，请参阅Servlet规范。

编写您的应用程序对此资源的使用对此资源环境引用的典型用法可能如下所示：

java">Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");writer.println("foo = " + bean.getFoo() + ", bar = " +bean.getBar());

配置Tomcat的资源工厂要配置Tomcat的资源工厂，请向此Web应用程序的元素添加如下所示的元素。

<Context ...>...<Resource name="bean/MyBeanFactory" auth="Container"type="com.mycompany.MyBean"factory="org.apache.naming.factory.BeanFactory"bar="23"/>...
</Context>

请注意，资源名称（在这里是bean/MyBeanFactory）必须与Web应用程序部署描述符中指定的值匹配。我们还初始化了bar属性的值，这将导致在返回新bean之前调用setBar(23)。因为我们没有初始化foo属性（虽然我们可以），所以bean将包含由其构造函数设置的任何默认值。

如果bean属性的类型为String，则BeanFactory将使用提供的属性值调用属性设置器。如果bean属性类型为原始类型或原始包装类型，则BeanFactory将将该值转换为适当的原始类型或原始包装类型，然后在调用setter时使用该值。某些bean具有无法从String自动转换的类型的属性。如果bean提供了一个具有相同名称但接受String的备用setter，则BeanFactory将尝试使用该setter。如果BeanFactory无法使用值或执行适当的转换，则设置属性将失败，并显示命名异常。

较早的Tomcat版本中可用的forceString属性已被删除，作为加强安全措施。