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的访问 - 看起来像这样:

// 获取我们的环境命名上下文
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类的新实例。

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

  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. 声明您的资源需求
    然后,修改您的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规范。

  1. 编写您的应用程序对此资源的使用
    对此资源环境引用的典型用法可能如下所示:
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. 配置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属性已被删除,作为加强安全措施。

热门相关:我的末世基地车   勇闯天涯   重生之男神追妻忙   神秘复苏   美女总裁之贴身高手