Apache Tomcat 11

0. はじめに

このリソースファクトリは、標準のJavaBean命名規約（つまり、引数なしのコンストラクタを持ち、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が実行されているユーザーのデフォルトのファイルパーミッションを継承します。インストールのセキュリティを維持するために、これらが適切であることを確認してください。

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

3. レルムを設定する

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

0. はじめに

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

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

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. レルムを設定する

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

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 Platform Specificationは、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 Standard Extension API (javax.sql.DataSource APIを含む)。このパッケージは現在「JDBC Optional Package」として知られています。
• 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：PreparedStatementsとCallableStatementsをプールするかどうか。デフォルト：false
• maxOpenPreparedStatements - ステートメントプールから同時に割り当てることができるオープンステートメントの最大数。デフォルト：-1 (無制限)
• defaultCatalog - デフォルトカタログの名前。デフォルト：設定なし
• connectionInitSqls - Connectionが作成された後に一度実行されるSQLステートメントのリスト。複数のステートメントはセミコロン（;）で区切ります。デフォルト：ステートメントなし
• connectionProperties - 接続作成のためにドライバに渡されるドライバ固有のプロパティのリスト。各プロパティはname=valueの形式で指定され、複数のプロパティはセミコロン（;）で区切られます。デフォルト：プロパティなし
• accessToUnderlyingConnectionAllowed - trueまたはfalse：基になる接続へのアクセスが許可されるかどうか。デフォルト：false

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