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）中，以定义资源：

• - 环境条目，一个单值参数，可用于配置应用程序的操作方式。

• - 资源引用，通常是指用于资源的对象工厂，例如JDBC DataSource、Jakarta Mail Session或配置到Tomcat中的自定义对象工厂。

• - 资源环境引用，Servlet 2.4中新增的一种资源引用变体，用于简化对不需要身份验证信息的资源的配置。 只要Tomcat能够识别一个适当的资源工厂来创建资源，并且不需要进一步的配置信息，Tomcat就会使用/WEB-INF/web.xml中的信息来创建资源。

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

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

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

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

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

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

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

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

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

// 获取我们的环境命名上下文
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();
1
2
3
4
5
6
7
8
9
10
11

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

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

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

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

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

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

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;
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

  
    MyBean实例的对象工厂。
  
  
    bean/MyBeanFactory
  
  
    com.mycompany.MyBean
  
1
2
3
4
5
6
7
8
9
10

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

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

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());
1
2
3
4
5

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

  ...
  
  ...
1
2
3
4
5
6
7

请注意，资源名称（在这里是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属性已被删除，作为加强安全措施。