Apache Tomcat 10

0. はじめに

このリソースファクトリは、標準の JavaBeans ネーミング規則（つまり、引数のないコンストラクタを持ち、setFoo() ネーミングパターンに準拠したプロパティセッターを持つ）に準拠する*任意*の Java クラスのオブジェクトを作成するために使用できます。リソースファクトリは、ファクトリの singleton 属性が false に設定されている場合にのみ、このエントリの lookup() が行われるたびに、適切な 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;
  }


}

2. リソース要件を宣言する

次に、Web アプリケーションのデプロイメント記述子（/WEB-INF/web.xml）を変更して、この Bean の新しいインスタンスを要求する JNDI 名を宣言します。最も簡単な方法は、次のように <resource-env-ref> 要素を使用することです。

<resource-env-ref>
  <description>
    Object factory for MyBean instances.
  </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 で必要な要素の順序を必ず守ってください！ 詳細については、サーブレット仕様 を参照してください。

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());

4. Tomcat のリソースファクトリを設定する

Tomcat のリソースファクトリを設定するには、この Web アプリケーションの <Context> 要素に次のような要素を追加します。

<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 は値を適切なプリミティブまたはプリミティブラッパーに変換し、セッターを呼び出すときにその値を使用します。一部の Bean には、String から自動的に変換できない型のプロパティがあります。Bean が String を受け取る同じ名前の代替セッターを提供している場合、BeanFactory はそのセッターを使用しようとします。BeanFactory が値を使用できない、または適切な変換を実行できない場合、プロパティの設定は NamingException で失敗します。

以前の Tomcat リリースで利用可能だった forceString プロパティは、セキュリティ強化策として削除されました。

0. はじめに

UserDatabase リソースは、通常、UserDatabase レルムで使用するためにグローバルリソースとして設定されます。Tomcat には、XML ファイル（通常は tomcat-users.xml）によってサポートされる UserDatabase リソースを作成する UserDatabaseFactory が含まれています。

グローバル UserDatabase リソースを設定するために必要な手順を以下に示します。

1. XML ファイルを作成/編集する

XML ファイルは通常 $CATALINA_BASE/conf/tomcat-users.xml にありますが、ファイルシステムのどこにでも配置できます。XML ファイルは $CATALINA_BASE/conf に配置することをお勧めします。一般的な XML は次のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="role1" password="tomcat" roles="role1"/>
</tomcat-users>

2. リソースを宣言する

次に、$CATALINA_BASE/conf/server.xml を変更して、XML ファイルに基づいて UserDatabase リソースを作成します。次のようになります。

<Resource name="UserDatabase"
          auth="Container"
          type="org.apache.catalina.UserDatabase"
          description="User database that can be updated and saved"
          factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
          pathname="conf/tomcat-users.xml"
          readonly="false" />

pathname 属性は、URL、絶対パス、または相対パスにすることができます。相対パスの場合、$CATALINA_BASE に相対します。

readonly 属性はオプションであり、指定しない場合はデフォルトで true になります。XML が書き込み可能な場合、Tomcat の起動時に書き込まれます。警告: ファイルが書き込まれる際、Tomcat を実行しているユーザーのデフォルトのファイル権限が継承されます。インストールのセキュリティを維持するために、これらの権限が適切であることを確認してください。

Realm で参照される場合、UserDatabase はデフォルトで pathname の変更を監視し、最終変更時刻に変更が observed された場合にファイルをリロードします。これは、watchSource 属性を false に設定することで無効にできます。

3. Realm の設定

Realm 設定ドキュメントに記載されているように、このリソースを使用するように UserDatabase Realm を設定します。

0. はじめに

Tomcat には、バックエンドとして DataSource リソースを使用する UserDatabase も含まれています。バックエンドリソースは、それを使用するユーザーデータベースと同じ JNDI コンテキストで宣言する必要があります。

グローバル UserDatabase リソースを設定するために必要な手順を以下に示します。

1. データベーススキーマ

ユーザーデータベースのデータベーススキーマは柔軟です。ユーザー（ユーザー名、パスワード）のテーブルと、各ユーザーに関連付けられたロールを一覧表示するもう1つのテーブルのみを使用して、DataSourceRealm に使用されるスキーマと同じにすることができます。完全な UserDatabase 機能をサポートするには、グループの追加テーブルを含める必要があり、ユーザー、グループ、およびロール間の参照整合性と互換性があります。

グループと参照整合性を備えたフル機能のスキーマは次のとおりです。

create table users (
  user_name         varchar(32) not null primary key,
  user_pass         varchar(64) not null,
  user_fullname     varchar(128)
  -- Add more attributes as needed
);

create table roles (
  role_name         varchar(32) not null primary key,
  role_description  varchar(128)
);

create table groups (
  group_name        varchar(32) not null primary key,
  group_description varchar(128)
);

create table user_roles (
  user_name         varchar(32) references users(user_name),
  role_name         varchar(32) references roles(role_name),
  primary key (user_name, role_name)
);

create table user_groups (
  user_name         varchar(32) references users(user_name),
  group_name        varchar(32) references groups(group_name),
  primary key (user_name, group_name)
);

create table group_roles (
  group_name        varchar(32) references groups(group_name),
  role_name         varchar(32) references roles(role_name),
  primary key (group_name, role_name)
);

グループを使用できない最小限のスキーマは次のとおりです（DataSourceRealm と同じです）。

create table users (
  user_name         varchar(32) not null primary key,
  user_pass         varchar(64) not null,
  -- Add more attributes as needed
);

create table user_roles (
  user_name         varchar(32),
  role_name         varchar(32),
  primary key (user_name, role_name)
);

2. リソースを宣言する

次に、$CATALINA_BASE/conf/server.xml を変更して、DataSource とそのスキーマに基づいて UserDatabase リソースを作成します。次のようになります。

<Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.DataSourceUserDatabaseFactory"
              dataSourceName="jdbc/authority" readonly="false"
              userTable="users" userNameCol="user_name" userCredCol="user_pass"
              userRoleTable="user_roles" roleNameCol="role_name"
              roleTable="roles" groupTable="groups" userGroupTable="user_groups"
              groupRoleTable="group_roles" groupNameCol="group_name" />

dataSourceName 属性は、UserDatabase のバックエンドとなる DataSource の JNDI 名です。 UserDatabase と同じ JNDI Context で宣言する必要があります。詳細な手順については、DataSource リソースのドキュメントを参照してください。

readonly 属性はオプションであり、指定しない場合はデフォルトで true になります。データベースが書き込み可能な場合、Tomcat 管理を介して UserDatabase に加えられた変更は、save 操作を使用してデータベースに永続化できます。

あるいは、バックエンドデータベースに直接変更を加えることもできます。

3. リソースの設定

4. Realm の設定

Realm 設定ドキュメントに記載されているように、このリソースを使用するように UserDatabase Realm を設定します。

0. はじめに

多くの Web アプリケーションでは、電子メールメッセージの送信はシステムの機能に必要な部分です。Jakarta Mail API は、このプロセスを比較的簡単に行いますが、クライアントアプリケーションが認識している必要がある多くの構成の詳細（メッセージ送信に使用する SMTP ホストの名前を含む）が必要です。

Tomcat には、SMTP サーバーに接続するように既に設定されている、jakarta.mail.Session セッションインスタンスを作成する標準リソースファクトリが含まれています。このようにして、アプリケーションはメールサーバーの設定環境の変更から完全に隔離されます。必要なときに、事前に設定されたセッションを要求して受信するだけです。

必要な手順の概要を以下に示します。

1. リソース要件の宣言

最初に行う必要があるのは、Web アプリケーションのデプロイメント記述子（/WEB-INF/web.xml）を変更して、事前に設定されたセッションを検索する JNDI 名を宣言することです。慣例により、そのようなすべての名前は、すべての提供されたリソースファクトリのルートである標準の java:comp/env ネーミングコンテキストを基準とした mail サブコンテキストに解決される必要があります。典型的な web.xml エントリは次のようになります。

<resource-ref>
  <description>
    Resource reference to a factory for jakarta.mail.Session
    instances that may be used for sending electronic mail
    messages, preconfigured to connect to the appropriate
    SMTP server.
  </description>
  <res-ref-name>
    mail/Session
  </res-ref-name>
  <res-type>
    jakarta.mail.Session
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>

警告 - Web アプリケーションのデプロイメント記述子の DTD で必要な要素の順序を必ず守ってください！ 詳細については、サーブレット仕様 を参照してください。

2. このリソースのアプリケーションの使用のコーディング

このリソース参照の一般的な使用法は次のようになります。

Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Session session = (Session) envCtx.lookup("mail/Session");

Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(request.getParameter("from")));
InternetAddress to[] = new InternetAddress[1];
to[0] = new InternetAddress(request.getParameter("to"));
message.setRecipients(Message.RecipientType.TO, to);
message.setSubject(request.getParameter("subject"));
message.setContent(request.getParameter("content"), "text/plain");
Transport.send(message);

アプリケーションは、Web アプリケーションのデプロイメント記述子で宣言されたのと同じリソース参照名を使用していることに注意してください。これは、以下で説明するように、Web アプリケーションの <Context> 要素で設定されているリソースファクトリと照合されます。

3. Tomcat のリソースファクトリの構成

Tomcat のリソースファクトリを設定するには、この Web アプリケーションの <Context> 要素に次のような要素を追加します。

<Context ...>
  ...
  <Resource name="mail/Session" auth="Container"
            type="jakarta.mail.Session"
            mail.smtp.host="localhost"/>
  ...
</Context>

リソース名（ここでは mail/Session）は、Web アプリケーションのデプロイメント記述子で指定された値と一致する必要があることに注意してください。 mail.smtp.host パラメーターの値をカスタマイズして、ネットワークに SMTP サービスを提供するサーバーを指すようにします。

追加のリソース属性と値は、プロパティと値に変換され、java.util.Properties コレクションの一部として jakarta.mail.Session.getInstance(java.util.Properties) に渡されます。Jakarta Mail 仕様の付録 A で定義されているプロパティに加えて、個々のプロバイダーは追加のプロパティもサポートする場合があります。

リソースが password 属性と mail.smtp.user 属性または mail.user 属性のいずれかで構成されている場合、Tomcat のリソースファクトリは jakarta.mail.Authenticator を構成してメールセッションに追加します。

4. Jakarta Mail API のインストール

Jakarta Mail API をダウンロードします.

配布パッケージを解凍し、jakarta.mail-api-2.1.0.jar を $CATALINA_HOME/lib に配置して、メールセッションリソースの初期化中に Tomcat で使用できるようにします。注：この jar を $CATALINA_HOME/lib と Web アプリケーションの lib フォルダーの両方に配置するとエラーが発生するため、$CATALINA_HOME/lib の場所にのみ配置されていることを確認してください。

5. 互換性のある実装をインストールする

互換性のある実装を選択して ダウンロード します。

実装を解凍し、jar ファイルを $CATALINA_HOME/lib に配置します。

注：他の実装が利用可能な場合があります

6. Tomcat を再起動します

追加の JAR を Tomcat で認識できるようにするには、Tomcat インスタンスを再起動する必要があります。

アプリケーション例

Tomcat に含まれている /examples アプリケーションには、このリソースファクトリを使用する例が含まれています。「JSP Examples」リンクからアクセスします。メールメッセージを実際に送信するサーブレットのソースコードは、/WEB-INF/classes/SendMailServlet.java にあります。

警告 - デフォルト構成では、localhost のポート 25 でリッスンしている SMTP サーバーがあると想定しています。そうでない場合は、この Web アプリケーションの <Context> 要素を編集し、mail.smtp.host パラメーターのパラメーター値をネットワーク上の SMTP サーバーのホスト名に変更します。

0. はじめに

多くの Web アプリケーションは、そのアプリケーションに必要な機能をサポートするために、JDBC ドライバーを介してデータベースにアクセスする必要があります。Jakarta EE プラットフォームの仕様では、Jakarta EE アプリケーションサーバーはこの目的のために *DataSource* 実装（つまり、JDBC 接続の接続プール）を利用できるようにする必要があります。Tomcat はまったく同じサポートを提供しているため、このサービスを使用して Tomcat で開発したデータベースベースのアプリケーションは、どの Jakarta EE サーバーでも変更なしで実行されます。

JDBC については、以下を参照してください。

• http://www.oracle.com/technetwork/java/javase/jdbc/index.html - Java Database Connectivity に関する情報のホームページ。
• http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html - JDBC 2.1 API 仕様。
• http://java.sun.com/products/jdbc/jdbc20.stdext.pdf - JDBC 2.0 標準拡張 API（javax.sql.DataSource API を含む）。このパッケージは、現在「JDBC オプションパッケージ」と呼ばれています。
• https://jakarta.ee/specifications/platform/9/ - Jakarta EE プラットフォーム仕様（すべての Jakarta EE プラットフォームがアプリケーションに提供する必要がある JDBC 機能を網羅しています）。

注 - Tomcat のデフォルトのデータソースサポートは、Commons プロジェクトの **DBCP 2** 接続プールに基づいています。ただし、以下で説明するように、独自のカスタムリソースファクトリを作成することにより、javax.sql.DataSource を実装する他の接続プールを使用することができます。

1. JDBC ドライバーのインストール

*JDBC データソース* JNDI リソースファクトリを使用するには、適切な JDBC ドライバーを Tomcat 内部クラスと Web アプリケーションの両方に使用できるようにする必要があります。これは、ドライバーの JAR ファイルを `$CATALINA_HOME/lib` ディレクトリにインストールすることで最も簡単に行えます。これにより、ドライバーはリソースファクトリとアプリケーションの両方で使用できるようになります。

2. リソース要件を宣言する

次に、Web アプリケーションのデプロイメント記述子（`/WEB-INF/web.xml`）を変更して、事前に設定されたデータソースを検索する JNDI 名を宣言します。慣例により、そのようなすべての名前は、すべての提供されたリソースファクトリのルートである標準の `java:comp/env` ネーミングコンテキストを基準とした `jdbc` サブコンテキストに解決される必要があります。典型的な `web.xml` エントリは次のようになります。

<resource-ref>
  <description>
    Resource reference to a factory for java.sql.Connection
    instances that may be used for talking to a particular
    database that is configured in the <Context>
    configuration for the web application.
  </description>
  <res-ref-name>
    jdbc/EmployeeDB
  </res-ref-name>
  <res-type>
    javax.sql.DataSource
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>

警告 - Web アプリケーションのデプロイメント記述子の DTD で必要な要素の順序を必ず守ってください！ 詳細については、サーブレット仕様 を参照してください。

3. このリソースを使用するアプリケーションのコードを作成する

このリソース参照の一般的な使用法は次のようになります。

Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
DataSource ds = (DataSource)
  envCtx.lookup("jdbc/EmployeeDB");

Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();

アプリケーションは、Web アプリケーションのデプロイメント記述子で宣言されたのと同じリソース参照名を使用していることに注意してください。これは、以下で説明するように、Web アプリケーションの <Context> 要素で設定されているリソースファクトリと照合されます。

4. Tomcat のリソースファクトリを設定する

Tomcat のリソースファクトリを設定するには、Web アプリケーションの `<Context>` 要素に次のような要素を追加します。

<Context ...>
  ...
  <Resource name="jdbc/EmployeeDB"
            auth="Container"
            type="javax.sql.DataSource"
            username="dbusername"
            password="dbpassword"
            driverClassName="org.hsql.jdbcDriver"
            url="jdbc:HypersonicSQL:database"
            maxTotal="8"
            maxIdle="4"/>
  ...
</Context>

リソース名（ここでは `jdbc/EmployeeDB`）は、Web アプリケーションのデプロイメント記述子で指定された値と一致する必要があることに注意してください。

この例では、HypersonicSQL データベース JDBC ドライバを使用していることを前提としています。実際のデータベースの JDBC ドライバと接続 URL に合わせて、driverClassName パラメータと driverName パラメータをカスタマイズしてください。

Tomcat の標準データソースリソースファクトリ (org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory) の構成プロパティは次のとおりです。

• driverClassName - 使用する JDBC ドライバの完全修飾 Java クラス名。
• username - JDBC ドライバに渡すデータベースユーザー名。
• password - JDBC ドライバに渡すデータベースパスワード。
• url - JDBC ドライバに渡す接続 URL。（下位互換性のために、driverName プロパティも認識されます。）
• initialSize - プール初期化中にプールに作成される初期接続数。デフォルト：0
• maxTotal - このプールから同時に割り当てることができる最大接続数。デフォルト：8
• minIdle - このプールに同時にアイドル状態になる最小接続数。デフォルト：0
• maxIdle - このプールに同時にアイドル状態になることができる最大接続数。デフォルト：8
• maxWaitMillis - 使用可能な接続がない場合に、プールが接続が返されるのを待つ最大ミリ秒数。これを超えると例外がスローされます。デフォルト：-1（無限）

接続の検証を処理する追加のプロパティがあります。

• validationQuery - アプリケーションに返される前に、プールが接続を検証するために使用できる SQL クエリ。指定する場合、このクエリは少なくとも 1 行を返す SQL SELECT ステートメントでなければなりません。
• validationQueryTimeout - 検証クエリのタイムアウト（秒単位）。デフォルト：-1（無限）
• testOnBorrow - true または false：プールから接続を借りるたびに、検証クエリを使用して接続を検証するかどうか。デフォルト：true
• testOnReturn - true または false：プールに接続を返すたびに、検証クエリを使用して接続を検証するかどうか。デフォルト：false

オプションのエビクタースレッドは、長時間アイドル状態になっている接続を削除することにより、プールの縮小を行います。エビクターは minIdle を考慮しません。設定された maxIdle プロパティに従ってプールを縮小する場合のみ、エビクタースレッドをアクティブにする必要はありません。

エビクターはデフォルトで無効になっており、次のプロパティを使用して設定できます。

• timeBetweenEvictionRunsMillis - エビクターの連続実行の間隔（ミリ秒単位）。デフォルト：-1（無効）
• numTestsPerEvictionRun - エビクターの実行ごとに、エビクターがアイドル状態を確認する接続の数。デフォルト：3
• minEvictableIdleTimeMillis - エビクターがプールから接続を削除できるアイドル時間（ミリ秒単位）。デフォルト：30*60*1000（30分）
• testWhileIdle - true または false：プールにアイドル状態になっている間に、エビクタースレッドが検証クエリを使用して接続を検証するかどうか。デフォルト：false

もう 1 つのオプション機能は、放棄された接続の削除です。アプリケーションが長時間プールに接続を返さない場合、接続は放棄されたと呼ばれます。プールは、このような接続を自動的に閉じてプールから削除できます。これは、アプリケーションが接続をリークする場合の回避策です。

放棄機能はデフォルトで無効になっており、次のプロパティを使用して設定できます。

• removeAbandonedOnBorrow - true または false：接続が借用されたときに、放棄された接続をプールから削除するかどうか。デフォルト：false
• removeAbandonedOnMaintenance - true または false：プールメンテナンス中に、放棄された接続をプールから削除するかどうか。デフォルト：false
• removeAbandonedTimeout - 借用された接続が放棄されたとみなされるまでの秒数。デフォルト：300
• logAbandoned - true または false：ステートメントまたは接続を放棄したアプリケーションコードのスタックトレースをログに記録するかどうか。これは深刻なオーバーヘッドを追加します。デフォルト：false

最後に、プールの動作をさらに微調整できるさまざまなプロパティがあります。

• defaultAutoCommit - true または false：このプールによって作成された接続のデフォルトの自動コミット状態。デフォルト：true
• defaultReadOnly - true または false：このプールによって作成された接続のデフォルトの読み取り専用状態。デフォルト：false
• defaultTransactionIsolation - デフォルトのトランザクション分離レベルを設定します。NONE、READ_COMMITTED、READ_UNCOMMITTED、REPEATABLE_READ、SERIALIZABLE のいずれかになります。デフォルト：デフォルト設定なし
• poolPreparedStatements - true または false：PreparedStatement と CallableStatement をプールするかどうか。デフォルト：false
• maxOpenPreparedStatements - ステートメントプールから同時に割り当てることができるオープンステートメントの最大数。デフォルト：-1（無制限）
• defaultCatalog - デフォルトカタログの名前。デフォルト：設定なし
• connectionInitSqls - 接続の作成後に一度だけ実行される SQL ステートメントのリスト。複数のステートメントはセミコロン（;）で区切ります。デフォルト：ステートメントなし
• connectionProperties - 接続を作成するためにドライバに渡されるドライバ固有のプロパティのリスト。各プロパティは name=value として指定され、複数のプロパティはセミコロン（;）で区切られます。デフォルト：プロパティなし
• accessToUnderlyingConnectionAllowed - true または false：基になる接続へのアクセスを許可するかどうか。デフォルト：false

詳細については、Commons DBCP 2 のドキュメントを参照してください。