Manager コンポーネント

目次

はじめに

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 には、使用するための 2 つの標準的な Manager の実装が用意されています。デフォルトの実装ではアクティブセッションが保存され、オプションの実装では（Tomcat の再起動時にセッションを保存することに加えて）適切な Store ネスト要素の使用によって選択されたストレージロケーションにスワップアウトされたアクティブセッションが保存されます。

標準 Manager 実装

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

属性説明
pathname

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

persistAuthentication

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

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

processExpiresFrequency

セッションの有効期限切れおよび関連するマネージャー操作の頻度。マネージャー操作は、指定されたバックグラウンド処理呼び出しの回数ごとに 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

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

sessionAttributeValueClassNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアル化されるセッション属性をフィルタリングするために使用される正規表現。属性は、値の実装クラス名がこのパターンに一致する場合にのみシリアル化されます。パターンが長さ 0 または null の場合、すべての属性が配布の対象となります。パターンはアンカーされているため、完全修飾クラス名はパターンに完全に一致する必要があります。指定しない場合は、デフォルト値の null が使用されます。ただし、SecurityManager が有効になっている場合、デフォルトは java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String; になります。

warnOnSessionAttributeFilterFailure

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

永続 Manager 実装

注：永続マネージャーが正しく機能するには、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 の対象となることに注意してください。そのようなフィルターが指定されている場合、または SecurityManager が有効になっている場合、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

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

sessionAttributeValueClassNameFilter

クラスタリング/レプリケーション、または永続ストアへの保存のためにシリアル化されるセッション属性をフィルタリングするために使用される正規表現。属性は、値の実装クラス名がこのパターンに一致する場合にのみシリアル化されます。パターンが長さ 0 または null の場合、すべての属性が配布の対象となります。パターンはアンカーされているため、完全修飾クラス名はパターンに完全に一致する必要があります。指定しない場合は、デフォルト値の null が使用されます。ただし、SecurityManager が有効になっている場合、デフォルトは java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String; になります。

warnOnSessionAttributeFilterFailure

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

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

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

すべての Manager 実装

すべての Manager 実装では、<SessionIdGenerator> 要素のネストが可能です。これは、セッション ID 生成の動作を定義します。SessionIdGenerator のすべての実装では、次の属性を使用できます。

属性説明
sessionIdLength

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

永続 Manager 実装

上記で説明したPersistent Manager 実装を使用している場合、永続データストレージの特性を定義する<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 リソースの How-To に示すように、プールされたプリペアドステートメントを設定することが推奨されます。

localDataSource

これにより、Store はグローバル DataSource ではなく、コンテキスト用に定義された 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 が正常にシャットダウンして再起動された場合、またはアプリケーションのリロードがトリガーされた場合、標準マネージャー実装は、pathname属性によって特定されたディスクファイルに現在アクティブなすべてのセッションをシリアル化しようとします。保存されたすべてのセッションは、アプリケーションのリロードが完了したときに、逆シリアル化されてアクティブ化されます（その間に期限切れになっていない場合）。

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

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

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

セッションの永続化を有効にする

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

<Manager pathname="SESSIONS.ser" />