Engineタグ

  • Tomcat Version:8.5.23

Engine要素は、特定のCatalinaサービスに関連付けられたリクエスト処理機構全体を表します。
1つ以上のコネクタからのすべての要求を受信して、
処理し、完了した応答をコネクタに返して、最終的にクライアントに送信します。

サービスに関連するすべての対応するConnector要素の後に、正確に1つのEngine要素をService要素内にネストしなければなりません。

Engineタグの補足説明

Tomcatの設定ファイルserver.xmlの概要図

「server.xmlの概要」で示したserver.xmlの概要図です。
１つのService要素の配下に１～複数のConnector要素を定義します。そのあとに１つのEngine要素を必ず定義します。

Engine要素とその配下のHost要素を定義すると、Tomcat初期起動時に「$CATALINA_BASE/conf/エンジン名/ホスト名」が自動生成されます。
このディレクトリ配下にWebアプリケーションの設定ファイルであるコンテキスト.xmlを格納するようにします。

server.xmlファイルのデフォルト値では、「$CATALINA_BASE/conf/Catalina/localhost」が自動生成されます。

Engingeタグ共通属性

Engineのすべての実装では、次の属性がサポートされています。

属性 未指定時の
デフォルト値		 説明
backgroundProcessorDelay 10(秒) この値は、このエンジン上のbackgroundProcessメソッドの呼び出しとすべてのホストおよびコンテキストを含む子コンテナの呼び出しの間の遅延を秒単位で表します。
子コンテナは、遅延値が負でない場合（つまり、独自の処理スレッドを使用している場合）、呼び出されません。
これを正の値に設定すると、スレッドが生成されます。
指定された時間待機すると、スレッドはこのエンジンとすべての子コンテナでbackgroundProcessメソッドを呼び出します。
指定しない場合、この属性のデフォルト値は10で、これは10秒の遅延を表します。
className org.apache.catalina.core.
StandardEngine		 使用する実装のJavaクラス名。このクラスは、org.apache.catalina.Engineインタフェースを実装する必要があります。
指定されていない場合は、org.apache.catalina.core.StandardEngineが使用されます。
defaultHost localhost サーバー上の[仮想]ホスト名(Hostタグのname属性で定義)に向けられたリクエストを処理しますが、
server.xmlファイルに対象の[仮想]ホスト名が存在しない場合に転送先となるデフォルトの[仮想]ホスト名をを指定します。
この名前は、EngineタグにネストされたHost要素のname属性と一致する必要があります。
jvmRoute System.
getProperty("jvmRoute")		 複数のTomcatサーバをロードバランサーでリクエストを振り分ける環境化の場合に、セッションの親和性を有効するために利用する識別子。
クラスタに参加する全てのTomcatサーバで一意になれなければならない識別子は、生成されたセッション識別子に追加されるため
フロントエンドプロキシは常に特定のセッションを同じTomcatインスタンスに転送できます。
Engine要素で明示されたjvmRouteは、システムプロパティの値が設定されている場合、システムプロパティの値は無視されます。 (筆者記)未定義時のデフォルト値は、JVMの起動オプション-DjvmRoute=hogehoge形式で指定した値です。
デフォルトのserver.xmlでは「jvm1」が指定されており、２号機には「jvm2」3号機には「jvm3」を指定するような例で記載されています。
name(必須) null このエンジンの論理名。ログおよびエラーメッセージで使用されます。
同じサーバー内で複数のサービス要素を使用する場合は、各エンジンに一意の名前を割り当てなければなりません。
startStopThreads 1 このエンジンが子ホスト要素を並列に開始するために使用するスレッドの数。
特別な値0は、使用されるRuntime.getRuntime()、availableProcessors() の値になります。
負数は、Runtime.getRuntime()になります。
これが1未満の場合を除いて、availableProcessors()+ 指定した値が使用されます。
この場合、1スレッドが使用されます。指定しない場合、デフォルト値の1が使用されます。 (筆者記)マルチコアのサーバーであれば0を指定することで
マルチコア数分のスレッドを生成するので処理が高速化されます。

Engineタグの子要素

このEngine要素内に1つまたは複数のHost要素をネストできます。それぞれのHost要素は、このサーバーに関連付けられた別の仮想ホストを表します。 少なくとも1つのホストが必要であり、ネストされたホストの1つに、上記のdefaultHost属性に指定された名前と一致する名前がなければなりません。

Engine要素内の対応する要素を入れ子にすることによって、以下のユーティリティコンポーネントのインスタンスを1つだけネストすることができます。

  • Realm - 下位レベルのRealm構成によって上書きされない限り、ユーザーのデータベースおよび関連する ロールをこのエンジン内にネストされたすべてのホストおよびコンテキスト間で共有できるように、レルムを構成します。

特記事項

ログ

エンジンは、org.apache.catalina.core.ContainerBase.[enginename]ログカテゴリに関連付けられています。
角括弧は実際には名前の一部であり、省略しないことに注意してください。

アクセスログ

Tomcatサーバーを実行すると、通常生成される出力ファイルの1つがアクセス・ログ($CATALINA_HOME/logs以下)になります。
アクセス・ログは、サーバーによって処理される各要求ごとに標準形式で1行の情報を生成します。
Catalinaには、Tomcatサーバーやカスタム形式で作成された同じ標準フォーマットでアクセスログを作成できるオプションのValve実装が含まれています。

Catalinaに、Engine、Host、Contextで処理されたすべてのリクエストに対するアクセスログを、次のようにValve要素を入れ子にして作成するように頼むことができます：

server.xmlのアクセスログ設定例
<Engine name="gakumon.tech" ...>

     <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
            prefix="gakumon.tech_access_log" suffix=".txt"
            pattern="%h %l %u %t "%r" %s %b" />
            
     ・・・・以下のHostタグを指定するが全てのタグに上記ログが適用されます。

</Engine>

サポートされているコンフィグレーション属性の詳細については、「ロギング・バルブにアクセスする」を参照してください。

Lifecycle Listeners

このエンジンがいつ起動または停止されたかを知る必要のあるJavaオブジェクトを実装している場合は、
この要素内のListener要素をネストして宣言できます。指定するクラス名は、org.apache.catalina.LifecycleListenerインタフェースを実装する必要があり、
対応するライフサイクルイベントの発生を通知されます。このようなリスナーの構成は次のようになります。

server.xmlのEngine内にリスナーを設定する例
<Engine name="gakumon.tech" ...>
・・・            
    <Listener className="com.mycompany.mypackage.MyListener" ... >
・・・            
</Engine>

リスナーは、この要素から構成できる追加のプロパティをいくつでも持つことができます。
属性名は、標準のプロパティーメソッド命名パターンを使用して、対応するJavaBeanプロパティー名と照合されます。

Request Filters

Catalinaに、周囲のエンジン、ホスト、またはコンテキスト要素に向けられたすべての着信要求に対して、
IPアドレスまたはホスト名をチェックするように頼むことができます。
リモートアドレスまたは名前は、java.util.regex正規表現構文を使用して定義された、設定された「受け入れ」かつ/又は「拒否」フィルタに対してチェックされます。
承認されていない場所からのリクエストは、HTTPの「禁止」エラーで拒否されます。フィルター宣言の例： 

server.xmlのEngine内にリスナーを設定する例
<Engine name="gakumon.tech" ...>
...
  <Valve className="org.apache.catalina.valves.RemoteHostValve"
         allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         deny="192\.168\.1\.\d+"/>
...
</Engine>

サポートされている構成オプションの詳細については、「リモートアドレスフィルタとリモートホストフィルタ」を参照してください。