マネージャーコンポーネント

目次

はじめに

Manager 要素は、関連するWebアプリケーションからの要求に応じてHTTPセッションを作成および維持するために使用される セッションマネージャー を表します。

Manager要素は Context コンポーネント内にネストすることができます。含まれていない場合、ほとんどの要件で十分なデフォルトのManager設定が自動的に作成されます — この設定の詳細については、以下の 標準Manager実装 を参照してください。

属性

共通属性

Manager のすべての実装は、以下の属性をサポートしています

属性説明
className

使用する実装のJavaクラス名です。このクラスは org.apache.catalina.Manager インターフェースを実装している必要があります。指定されていない場合、標準値（以下で定義）が使用されます。

maxActiveSessions

このManagerによって作成されるアクティブセッションの最大数、または制限なしの場合は -1（デフォルト）です。

制限に達すると、新しいセッションを作成しようとする試み（例: HttpServletRequest.getSession() の呼び出し）は IllegalStateException で失敗します。

notifyAttributeListenerOnUnchangedValue

属性がセッションに追加され、同じ名前の属性がすでにセッションに存在する場合、`HttpSessionAttributeListener` は属性が置き換えられたことを通知されます。指定されていない場合、デフォルト値の true が使用されます。

notifyBindingListenerOnUnchangedValue

属性がセッションに追加され、同じ名前の属性がすでにセッションに存在し、その属性が HttpSessionBindingListener を実装している場合、リスナーは属性がアンバインドされ、再度バインドされたことを通知されます。指定されていない場合、デフォルト値の false が使用されます。

sessionActivityCheck

これが true の場合、Tomcatは各セッションのアクティブリクエスト数を追跡します。セッションが有効かどうかを判断する際、少なくとも1つのアクティブリクエストを持つセッションは常に有効と見なされます。

org.apache.catalina.STRICT_SERVLET_COMPLIANCE が true に設定されている場合、この設定のデフォルトは true になります。それ以外の場合、デフォルト値は false になります。

sessionLastAccessAtStart

これが true の場合、セッションの最終アクセス時刻は前回のリクエストの開始時点から計算されます。false の場合、セッションの最終アクセス時刻は前回のリクエストの終了時点から計算されます。これはアイドル時間の計算方法にも影響します。

org.apache.catalina.STRICT_SERVLET_COMPLIANCE が true に設定されている場合、この設定のデフォルトは true になります。それ以外の場合、デフォルト値は false になります。

標準実装

Tomcatは、使用するために Manager の2つの標準実装を提供します — デフォルトのものはアクティブセッションを格納し、オプションのものは、適切な Store ネスト要素の使用によって選択されたストレージ場所に、スワップアウトされたアクティブセッション（Tomcatの再起動時にセッションを保存することに加えて）を格納します。

標準マネージャー実装

Manager の標準実装は org.apache.catalina.session.StandardManager です。これは（上記の共通属性に加えて）以下の追加属性をサポートします

属性説明
pathname

セッションの状態が可能な限りアプリケーションの再起動時にも保持されるファイルの、絶対パス名または相対パス名（このContextの作業ディレクトリに対する）。デフォルトはnullです。
詳細については、再起動時の永続化 を参照してください。この永続化は、この属性に空でない文字列を設定することで有効にできます。

persistAuthentication

アプリケーションの再起動時にセッションの状態が保持される場合、認証情報を含めるべきですか？true の場合、セッションの認証は保持され、アプリケーションが再起動された後もセッションは認証されたままになります。指定されていない場合、デフォルト値の false が使用されます。
詳細については、再起動時の永続化 を参照してください。

セッションの Principal クラスとその派生クラスはすべて sessionAttributeValueClassNameFilter の対象となることに注意してください。そのようなフィルタが指定されている場合、`Principal` クラスおよび派生クラスの名前は、復元されるためにそのフィルタパターンと一致する必要があります。

processExpiresFrequency

セッションの有効期限、および関連するマネージャー操作の頻度。マネージャー操作は、指定された回数のbackgroundProcess呼び出しごとに1回実行されます（つまり、回数が少ないほど、チェックは頻繁に行われます）。最小値は1で、デフォルト値は6です。

secureRandomClass

セッションIDの生成に使用する java.security.SecureRandom を拡張するJavaクラス名。指定されていない場合、デフォルト値は java.security.SecureRandom です。

secureRandomProvider

セッションIDを生成する java.security.SecureRandom インスタンスを作成するために使用するプロバイダーの名前。無効なアルゴリズムやプロバイダーが指定された場合、Managerはプラットフォームのデフォルトプロバイダーとデフォルトアルゴリズムを使用します。指定されていない場合、プラットフォームのデフォルトプロバイダーが使用されます。

secureRandomAlgorithm

セッションIDを生成する java.security.SecureRandom インスタンスを作成するために使用するアルゴリズムの名前。無効なアルゴリズムやプロバイダーが指定された場合、Managerはプラットフォームのデフォルトプロバイダーとデフォルトアルゴリズムを使用します。指定されていない場合、デフォルトのSHA1PRNGアルゴリズムが使用されます。デフォルトアルゴリズムがサポートされていない場合は、プラットフォームのデフォルトが使用されます。プラットフォームのデフォルトを使用することを指定するには、secureRandomProvider属性を設定せず、この属性を空文字列に設定します。

sessionAttributeNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアライズされるセッション属性をフィルタリングするために使用される正規表現。属性は、その名前がこのパターンと一致する場合にのみシリアライズされます。パターンがゼロ長または null の場合、すべての属性が分散の対象となります。パターンはアンカーされるため、セッション属性名はパターンに完全に一致する必要があります。例として、値 (userName|sessionHistory) は、userName と sessionHistory という名前の2つのセッション属性のみを分散します。指定されていない場合、デフォルト値の null が使用されます。

sessionAttributeValueClassNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアライズされるセッション属性をフィルタリングするために使用される正規表現。属性は、その値の実装クラス名がこのパターンと一致する場合にのみシリアライズされます。パターンがゼロ長または null の場合、すべての属性が分散の対象となります。パターンはアンカーされるため、完全修飾クラス名はパターンに完全に一致する必要があります。指定されていない場合、デフォルト値の null が使用されます。

warnOnSessionAttributeFilterFailure

sessionAttributeNameFilter または sessionAttributeValueClassNameFilter が属性をブロックした場合、これは WARN レベルでログに記録されるべきですか？WARN レベルのログ記録が無効になっている場合、DEBUG でログに記録されます。この属性のデフォルト値は false です。

永続マネージャー実装

注意: 永続マネージャーが正しく機能するためには、org.apache.catalina.session.StandardSession.ACTIVITY_CHECK または org.apache.catalina.STRICT_SERVLET_COMPLIANCE のいずれかの システムプロパティ を true に設定する必要があります。

Manager の永続実装は org.apache.catalina.session.PersistentManager です。セッションの作成と削除という通常の操作に加えて、PersistentManager には、アクティブ（ただしアイドル状態）なセッションを永続ストレージメカニズムにスワップアウトする機能、およびTomcatの通常の再起動時にすべてのセッションを保存する機能があります。実際に使用される永続ストレージメカニズムは、Manager 要素内にネストされたStore要素の選択によって決定されます — これは PersistentManager を使用するために必須です。

このManager実装は、先に説明した 共通属性 に加えて、以下の属性をサポートします。

属性説明
className

上記の 共通属性 で説明されているのと同じ意味を持ちます。このマネージャー実装を使用するには、org.apache.catalina.session.PersistentManager を**必ず**指定する必要があります。

maxIdleBackup

セッションストアへの永続化の対象となるまでに、セッションへの最終アクセスからの時間間隔（秒単位）。この機能を無効にするには -1 を指定します。デフォルトでは、この機能は無効です。

maxIdleSwap

非アクティブのためにセッションがディスクにスワップされる対象となるまでの、セッションがアイドル状態である最大時間。これを -1 に設定すると、セッションは非アクティブであるという理由だけでスワップアウトされません。この機能が有効な場合、ここで指定された時間間隔は maxIdleBackup で指定された値以上である必要があります。デフォルトでは、この機能は無効です。

minIdleSwap

アクティブセッション数をmaxActiveSessions以下に保つために、セッションがディスクにスワップされる対象となるまでにアイドル状態である必要がある最小時間（秒単位）。-1 に設定すると、アクティブセッション数を減らすためにセッションがスワップアウトされることはありません。指定された場合、この値は maxIdleSwap で指定された値よりも小さくなければなりません。デフォルトでは、この値は -1 に設定されています。

persistAuthentication

セッションが永続ストレージにスワップアウトされる際、認証情報を含めるべきですか？true の場合、セッションの認証は保持され、永続ストレージから再ロード（スワップイン）された後もセッションは認証されたままになります。指定されていない場合、デフォルト値の false が使用されます。

セッションの Principal クラスとその派生クラスはすべて sessionAttributeValueClassNameFilter の対象となることに注意してください。そのようなフィルタが指定されている場合、`Principal` クラスおよび派生クラスの名前は、復元されるためにそのフィルタパターンと一致する必要があります。

processExpiresFrequency

これは、上記の org.apache.catalina.session.StandardManager クラスについて説明されているものと同じです。

saveOnRestart

Tomcatがシャットダウンおよび再起動されたとき（またはこのアプリケーションがリロードされたとき）に、すべてのセッションを永続化して再ロードすべきですか？デフォルトでは、この属性は true に設定されています。

secureRandomClass

これは、上記の org.apache.catalina.session.StandardManager クラスについて説明されているものと同じです。

secureRandomProvider

これは、上記の org.apache.catalina.session.StandardManager クラスについて説明されているものと同じです。

secureRandomAlgorithm

これは、上記の org.apache.catalina.session.StandardManager クラスについて説明されているものと同じです。

sessionAttributeNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアライズされるセッション属性をフィルタリングするために使用される正規表現。属性は、その名前がこのパターンと一致する場合にのみシリアライズされます。パターンがゼロ長または null の場合、すべての属性が分散の対象となります。パターンはアンカーされるため、セッション属性名はパターンに完全に一致する必要があります。例として、値 (userName|sessionHistory) は、userName と sessionHistory という名前の2つのセッション属性のみを分散します。指定されていない場合、デフォルト値の null が使用されます。

sessionAttributeValueClassNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアライズされるセッション属性をフィルタリングするために使用される正規表現。属性は、その値の実装クラス名がこのパターンと一致する場合にのみシリアライズされます。パターンがゼロ長または null の場合、すべての属性が分散の対象となります。パターンはアンカーされるため、完全修飾クラス名はパターンに完全に一致する必要があります。指定されていない場合、デフォルト値の null が使用されます。

warnOnSessionAttributeFilterFailure

sessionAttributeNameFilter または sessionAttributeValueClassNameFilter が属性をブロックした場合、これは WARN レベルでログに記録されるべきですか？WARN レベルのログ記録が無効になっている場合、DEBUG でログに記録されます。この属性のデフォルト値は false です。

PersistentManagerを正常に使用するには、以下で説明するように、その内部に <Store> 要素をネストする必要があります。

ネストされたコンポーネント

すべてのマネージャー実装

すべてのManager実装は、<SessionIdGenerator> 要素のネストを許可します。これはセッションID生成の動作を定義します。SessionIdGenerator のすべての実装は、以下の属性を許可します

属性説明
sessionIdLength

セッションIDの長さは、sessionIdLength 属性で変更できます。

永続マネージャー実装

上記で説明した 永続マネージャー実装 を使用している場合、永続データストレージの特性を定義する <Store> 要素をその内部に**必ず**ネストする必要があります。現在、異なる特性を持つ <Store> 要素の2つの実装が利用可能です。以下で説明します。

ファイルベースストア

ファイルベースストア 実装は、スワップアウトされたセッションを設定可能なディレクトリ内の個別のファイル（セッション識別子に基づいて命名）に保存します。したがって、アクティブセッション数が増加するにつれてスケーラビリティの問題に直面する可能性があり、これは主に簡単に実験する手段と見なすべきです。

これを設定するには、<Manager> 要素内に <Store> をネストし、以下の属性を追加します

属性説明
className

使用する実装のJavaクラス名です。このクラスは org.apache.catalina.Store インターフェースを実装している必要があります。この実装を使用するには、org.apache.catalina.session.FileStore を**必ず**指定する必要があります。

directory

個々のセッションファイルが書き込まれるディレクトリの、絶対パス名または相対パス名（このWebアプリケーションのテンポラリ作業ディレクトリに対する）。指定されていない場合、コンテナによって割り当てられたテンポラリ作業ディレクトリが使用されます。

データソースベースストア

データソースベースストア 実装は、スワップアウトされたセッションを、データソースを介してアクセスされるデータベース内の事前設定されたテーブルの個々の行に保存します。多数のスワップアウトされたセッションがある場合、この実装は上記のファイルベースストアよりも改善されたパフォーマンスを示します。

これを設定するには、<Manager> 要素内に <Store> をネストし、以下の属性を追加します

属性説明
className

使用する実装のJavaクラス名です。このクラスは org.apache.catalina.Store インターフェースを実装している必要があります。この実装を使用するには、org.apache.catalina.session.DataSourceStore を**必ず**指定する必要があります。

dataSourceName

JDBC DataSourceファクトリのJNDIリソース名です。このコードはプリペアドステートメントを使用するため、JNDIリソースのハウツー に示されているように、プールされたプリペアドステートメントを設定することをお勧めします。

localDataSource

これにより、ストアはグローバルDataSourceではなく、Contextに定義されたDataSourceを使用できます。指定されていない場合、デフォルトは false です: グローバルDataSourceを使用します。

sessionAppCol

指定されたセッションテーブルに含まれるデータベースカラム名で、`/Engine/Host/Context` の形式でEngine、Host、Webアプリケーションのコンテキスト名を含みます。指定されていない場合、デフォルト値の app が使用されます。

sessionDataCol

指定されたセッションテーブルに含まれるデータベースカラム名で、スワップアウトされたセッションのすべてのセッション属性のシリアライズ形式を含みます。カラムタイプはバイナリオブジェクト（通常はBLOBと呼ばれる）を受け入れる必要があります。指定されていない場合、デフォルト値の data が使用されます。

sessionIdCol

指定されたセッションテーブルに含まれるデータベースカラム名で、スワップアウトされたセッションのセッション識別子を含みます。カラムタイプは、Tomcatによって作成されたセッション識別子に含まれる文字数（通常は32）以上の文字データを扱う必要があります。指定されていない場合、デフォルト値の id が使用されます。

sessionLastAccessedCol

指定されたセッションテーブルに含まれるデータベースカラム名で、このセッションの lastAccessedTime プロパティを含みます。カラムタイプはJava long（64ビット）を受け入れる必要があります。指定されていない場合、デフォルト値の maxinactive が使用されます。

sessionMaxInactiveCol

指定されたセッションテーブルに含まれるデータベースカラム名で、このセッションの maxInactiveInterval プロパティを含みます。カラムタイプはJava integer（32ビット）を受け入れる必要があります。指定されていない場合、デフォルト値の maxinactive が使用されます。

sessionTable

スワップアウトされたセッションを保存するために使用されるデータベーステーブル名。このテーブルは、この要素の他の属性によって設定されるデータベースカラムを（少なくとも）含む必要があります。指定されていない場合、デフォルト値の tomcat$sessions が使用されます。

sessionValidCol

指定されたセッションテーブルに含まれるデータベースカラム名で、このスワップアウトされたセッションがまだ有効であるかどうかのフラグを含みます。カラムタイプは単一の文字を受け入れる必要があります。指定されていない場合、デフォルト値の valid が使用されます。

データソースストアを初めて使用する前に、スワップアウトされたセッションを保存するために使用されるテーブルを作成する必要があります。詳細なSQLコマンドは使用しているデータベースによって異なりますが、一般的にこのようなスクリプトが必要になります

create table tomcat_sessions (
  session_id     varchar(100) not null primary key,
  valid_session  char(1) not null,
  max_inactive   int not null,
  last_access    bigint not null,
  app_name       varchar(255),
  session_data   mediumblob,
  KEY kapp_name(app_name)
);

注: 上記のSQLコマンドは、テーブル名またはカラム名のいずれについてもデフォルト名を使用していないため、データソースストアはこれを反映するように設定する必要があります。

特殊機能

再起動時の永続化

Apache Tomcatが正常にシャットダウンされて再起動されるたび、またはアプリケーションのリロードがトリガーされるたびに、標準のManager実装は、現在アクティブなすべてのセッションを pathname 属性で指定されたディスクファイルにシリアライズしようとします。保存されたセッションはすべて、アプリケーションのリロードが完了したときに（その間に期限切れになっていないと仮定して）デシリアライズされ、アクティブ化されます。

セッション属性の状態を正常に復元するには、それらのすべての属性が java.io.Serializable インターフェースを実装している**必要があります**。Webアプリケーションのデプロイメント記述子（/WEB-INF/web.xml）に <distributable> 要素を含めることで、Managerにこの制限を強制させることができます。

persistAuthentication も true に設定されている場合、認証の永続化を正しく機能させるには、セッションに存在する Principal クラスも java.io.Serializable インターフェースを実装している**必要がある**ことに注意してください。その Principal クラスの実際の型は、アプリケーションで使用される Realm 実装によって決定されます。ほとんどのRealm（JAASRealm を除く）によってインスタンス化されるTomcatの標準 Principal クラスは java.io.Serializable を実装しています。

StandardManager によって提供される再起動時の永続化は、PersistentManager によって提供されるものよりも単純な実装です。堅牢で本番品質の再起動時の永続化が必要な場合は、適切な設定で PersistentManager を使用する必要があります。

セッション永続化の有効化

上記で文書化されているように、すべてのWebアプリケーションはデフォルトで標準マネージャー実装が設定されており、再起動時のセッション永続化を実行できます。この永続化機能を有効にするには、Webアプリケーションの Context 設定ファイルを作成し、以下の要素を追加します（この例では、セッションは SESSIONS.ser という名前のファイルに保存されます）

<Manager pathname="SESSIONS.ser" />