ロギングツールキットの使い方

ロギングは、アダプタコンポーネントに不可欠な機能です。通常、アダプタは複数のアプリケーションの統合に使用され、データの処理時にエンドユーザとは対話しません。フロントエンドコンポーネントとは異なり、アダプタにエラーや警告が発生すると、処理を中断してエンドユーザの応答を待つことができません。

ADK では、ロギングフレームワークを実装することにより、アダプタアクティビティのログを記録できます。このフレームワークにより、複数の出力先へのインターナショナライズまたはローカライズされたメッセージを記録できます。また、メッセージ、カテゴリ、優先度、フォーマット、および送信先を調整するためのさまざまなコンフィグレーションパラメータを使用できます。

ロギングツールキット

ADK のロギングツールを使用すると、インターナショナライズされたメッセージを複数の出力先にログとして記録できます。ロギングツールキットを使用すると、Apache Log4j オープンソースプロジェクトの機能が強化されます。そのため、この製品には、Apache Software Foundation (http://www.apache.org) によって開発されたソフトウェアが組み込まれています。

ロギングツールキットは、必要な Log4j クラスをラップし、J2EE 準拠アダプタに機能を追加するためのフレームワークです。このツールキットは、WLI_HOME/lib ディレクトリの logtoolkit.jar ファイル内にあります。logtoolkit.jar ファイルは、DOM、XERCES、および Log4j に依存します。XERCES の依存関係には、WebLogic Server で提供される weblogic.jar ファイルと xmlx.jar ファイルが必要です。log4j.jar は、WL_HOME/common/lib にあります。

Log4j パッケージは、オープンソースイニシアチブによって認可されたオープンソースの完全ライセンス、Apache 公用ライセンスに従って配布されています。すべてのソースコード、クラスファイル、およびドキュメントが含まれた最新バージョンの Log4j は、Apache Log4j Web サイト (http://www.apache.org) にあります。

ロギングコンフィグレーションファイル

この節では、ロギングコンフィグレーションファイルへの参照や、このファイルのコードの抜粋を紹介します。ロギングコンフィグレーションファイルは、BEA_WLS_DBMS_ADK.xml などのアダプタ論理名で識別される .xml ファイルです。このファイルには、「ロギングの概念」で説明されている 4 つのロギングの概念に関する基本情報が定義されており、使用するアダプタに合わせて変更できます。

ADK では、WLI_HOME/adapters/sample/src に基本的なロギングコンフィグレーションファイル BEA_WLS_SAMPLE_ADK.xml が格納されています。このファイルを使用するアダプタに合わせて変更する場合は、GenerateAdapterTemplate を実行してください。このユーティリティを使用すると、サンプルバージョンのロギングコンフィグレーションファイルを、開発者の新しいアダプタに関連する情報に基づいてカスタマイズし、そのカスタマイズバージョンのファイルを新しいアダプタの開発環境で使用できます。GenerateAdapterTemplate の詳細については、「カスタム開発環境の作成」を参照してください。

ロギングの概念

ADK のロギングツールキットを使用する前に、ロギングフレームワークの主要概念を理解する必要があります。ロギングには、次の 4 つの主要コンポーネントがあります。

これらのコンポーネントは連携して機能し、メッセージタイプと優先度に従ってメッセージを記録し、実行時にはメッセージのフォーマットや出力先を管理できます。

メッセージカテゴリ

カテゴリは、定義された基準に従ってログメッセージを識別するロギングフレームワークの中心的な概念です。ADK では、カテゴリは BEA_WLS_SAMPLE_ADK.DesignTime のように名前で識別されます。

カテゴリは階層で定義されており、どのカテゴリも親カテゴリからプロパティを継承できます。階層は以下のように定義されています。

たとえば、以下の図に示すように、BEA_WLS_SAMPLE_ADK.DesignTime は BEA_WLS_SAMPLE_ADK の子孫で、さらに BEA_WLS_SAMPLE_ADK はルートカテゴリの子孫になります。

ルートカテゴリはカテゴリ階層の最上位にあり、削除したり名前で検索できません。

カテゴリを作成する場合は、アダプタのコンポーネントに対応した名前を割り当てます。たとえば、アダプタに設計時ユーザインタフェースコンポーネントがある場合は、次のようなカテゴリ名にします。BEA_WLS_SAMPLE_ADK.DesignTime

メッセージ優先度

どのメッセージにも、重要度を示す優先度があります。メッセージの優先度は、メッセージの記録に使用される ILogger インタフェースメソッドによって決まります。たとえば、ILogger インスタンスでデバッグメソッドを呼び出した場合は、デバッグメッセージが生成されます。

ロギングツールキットには、メッセージに対する 5 つの優先度があります。これらを重要度の高い順に表 5-1 に示します。

表 5-1 ロギングツールキットの優先度
優先度	意味
`AUDIT`	アダプタが実行するビジネス処理に関連した特に重要なログメッセージ。この重要度のメッセージは常にログに書き出される。
`ERROR`	アダプタに発生したエラー。エラーメッセージは、ユーザに合わせてインターナショナライズおよびローカライズされる。
`WARN`	エラーではないが、アダプタに問題を引き起こす可能性がある状態。警告メッセージは、ユーザに合わせてインターナショナライズおよびローカライズされる。
`INFO`	ユーザに合わせてインターナショナライズおよびローカライズされる情報メッセージ。
`DEBUG`	デバッグメッセージ。コンポーネントの内部要素がどのように機能しているかを調べるために使用される情報。通常、デバッグメッセージはインターナショナライズされない。

BEA_WLS_SAMPLE_ADK カテゴリには下記の子要素があるので、優先度は「WARN」になります。

優先度に使用されるクラスは、com.bea.logging.LogPriority である必要があります。

カテゴリへの優先度の割り当て

カテゴリには優先度を割り当てることができます。カテゴリに優先度が割り当てられていない場合、そのカテゴリの優先度は、優先度が割り当てられている最も近い祖先から継承されます。つまり、カテゴリに継承される優先度は、そのカテゴリの階層の上位をたどり、最初に見つかった NULL でない優先度になります。

ログメッセージは、優先度がそのカテゴリの優先度以上の場合に、ログの出力先に送られます。それ以外の場合は、メッセージはログに書き込まれません。優先度が割り当てられていないカテゴリは、階層から優先度が継承されます。最終的にすべてのカテゴリに優先度が継承されるようにするには、ルートカテゴリに必ず優先度を割り当てる必要があります。カテゴリに継承されている優先度が q で、そのカテゴリ内のログ文の優先度が p の場合、p >= q の場合にロギングが有効になります。ただし、このルールでは、優先度の順位が DEBUG < INFO < WARN < ERROR < AUDIT であるという前提に基づきます。

メッセージアペンダ

ロギングフレームワークでは、アペンダと呼ばれるインタフェースを使用することにより、1 つのアダプタで複数の出力先にログメッセージを転送できます。Log4j には、以下の出力先に対応するアペンダがあります。

また、ADK のロギングツールキットには、ご使用の WebLogic Server ログにログメッセージを送信するために、呼び出せるアペンダも用意されています。

1 つのカテゴリが、複数のアペンダを参照できます。あるカテゴリで有効なロギング要求は、カテゴリ階層の上位にあるすべてのアペンダと、カテゴリ内にあるすべてのアペンダに転送されます。つまり、アペンダはカテゴリ階層から累加的に継承されます。

たとえば、コンソールアペンダがルートカテゴリに追加されると、有効なロギング要求はすべてコンソールに表示されます。さらにファイルアペンダがカテゴリ C に追加されると、カテゴリ C と C の子カテゴリの有効なロギング要求はファイルに出力され、コンソールに表示されます。このようなデフォルトの動作を無効にする (アペンダの累加的な継承を止める) には、累加フラグを false に設定します。

コードリスト 5-1 は、WebLogic Server ログに対するアペンダを示します。

メッセージレイアウト

Log4j では、レイアウトをアペンダに関連付けることでログメッセージのフォーマットをカスタマイズできます。レイアウトによってログメッセージのフォーマットが決定され、アペンダはフォーマットされたメッセージを出力先に転送します。ロギングツールキットでは、通常 PatternLayout を使用してログメッセージのフォーマットを設定します。PatternLayout は標準 Log4j 配布キットに含まれており、これを使用することで C 言語の printf 関数に似た変換パターンに従って出力フォーマットを指定できます。

たとえば、変換パターンが「%-5p%d{DATE} %c{4} %x - %m%n」の PatternLayout を呼び出すと、次のようなメッセージが生成されます。

%-5p は、メッセージの優先度を示す。上記の例では AUDIT です。
%d{DATE} は、メッセージの日付を示す。上記の例では 21 May 2001 11:00:57,109 です。
%c{4} は、ログメッセージのカテゴリを示す。上記の例では BEA_WLS_SAMPLE_ADK です。

コンポーネントの結合

コードリスト 5-2 では、サンプルアダプタの新しいカテゴリを宣言し、新しいカテゴリに優先度を関連付け、アペンダを宣言することでログメッセージの送信先のファイルのタイプを指定しています。



重要! アダプタのルート カテゴリ。これをユニークにすることで、
他のアダプタによるカテゴリへのロギングを防ぐ。
--> 
 
<category name='BEA_WLS_SAMPLE_ADK' class='com.bea.logging.LogCategory'>
  <!-
    デフォルト優先度 (レベルで実行時に変更可能)
    DEBUG は、アダプタのコード ベースの全メッセージ。
    INFO は、情報、警告、エラー、監査ログ。
    WARN は、警告、エラー、監査ログ。
    ERROR は、エラー、監査ログ。
    AUDIT は、監査ログのみ。
  --> 
 
    <priority value='WARN' class='com.bea.logging.LogPriority'/> 
   <appender-ref ref='WebLogicAppender'/>
 
</category>

ロギングの設定方法

アダプタに対してロギングフレームワークをセットアップするには

アダプタで使用されるすべての基本コンポーネントを確認します。たとえば、アダプタに EventGenerator があれば、EventGenerator コンポーネントが必要です。また、アダプタが設計時 GUI をサポートしている場合は、設計時コンポーネントが必要です。
複製したアダプタから、基本ログコンフィグレーションファイルを開きます。このファイルは、WLI_HOME/adapters/ADAPTER/src/ フォルダにあります。ファイルの拡張子は .xml です。たとえば、DBMS サンプルアダプタコンフィグレーションファイルは、WLI_HOME/adapters/dbms/src/BEA_WLS_DBMS_ADK.xml です。
基本ログコンフィグレーションファイルに、手順 1 で確認したすべてのアダプタコンポーネントのカテゴリ要素を追加します。各カテゴリ要素に優先度を設定します。コードリスト 5-3 に、優先度が DEBUG である EventGenerator のカテゴリを追加する方法を示します。

コードリスト 5-3 EventGenerator ログカテゴリを優先度 DEBUG で追加するサンプルコード

<category name='BEA_WLS_DBMS_ADK.EventGenerator'
            class='com.bea.logging.LogCategory'>
    <priority value='DEBUG'
              class='com.bea.logging.LogPriority'/>
</category>

必要なアペンダを決め、そのアペンダをコンフィグレーションファイルで指定します。必要に応じて、メッセージフォーマット情報を追加します。コードリスト 5-4 には、<appender> 要素内に基本ファイルアペンダを追加する方法を示します。<layout> 要素内の指示により、メッセージフォーマットを特定します。

注意 : WebLogic Integration に用意されているすべてのサンプルアダプタでは、WebLogicAppender がデフォルトで使用されています。

コードリスト 5-4 ファイルアペンダおよびレイアウトパターンを追加するサンプルコード

<!-- 基本ファイル アペンダ -->

<appender name='FileAppender'
   class='org.apache.Log4j.FileAppender'>

    <!-- 出力をファイルに送信 -->

    <param name='File' value='BEA_WLS_DBMS_ADK.log'/>

    <!-- 既存を短縮 -->

    <param name="Append" value="true"/>

    <!-- 基本 LOG4J パターン レイアウトを使用 -->

    <layout class='org.apache.Log4j.PatternLayout'>
       <param name='ConversionPattern' value='%-5p %d{DATE} %c{4}
         %x - %m%n'/>
    </layout>		

</appender>

ここで、以下のコンフィグレーションファイルの設定を確認します。

WLI_HOME/adapters/ADAPTER/src/rar/META-INF/ra.xml および weblogic-ra.xml - AbstractManagedConnectionFactory が、この基本コンフィグレーションファイルに入力されたロギング情報を使用して、初期化時にログフレームワークのコンフィグレーションを行う。
WLI_HOME/adapters/ADAPTER/src/war/web-inf/web.xml - RequestHandler (AbstractDesignTimeRequestHandler の親) が、この基本コンフィグレーションファイルに入力されたロギング情報を使用して、初期化時にログフレームワークのコンフィグレーションを行う。

これらのパスの ADAPTER はアダプタ名を示します。たとえば、DBMS サンプルアダプタの場合、関連するコンフィグレーションファイルのパス名は以下のようになります。

ロギングフレームワークのクラス

ロギングフレームワークの基本的概念を踏まえ、さらにロギングツールキットに用意されている以下の 3 つのメインクラスを理解する必要があります。

com.bea.logging.ILogger

このクラスは、ロギングフレームワークのメインインタフェースです。メッセージロギング用の便利なメソッドが多数あります。

基本ログコンフィグレーションファイルでロギングをコンフィグレーションする方法については、「ロギングの設定方法」を参照してください。また、以下のロギングメソッドを実装しても、プログラム的にロギングのコンフィグレーションを行うことができます。

logger.setPriority ("DEBUG") - 現在の ILogger から出力されるメッセージの最低優先度を変更します。
logger.addRuntimeDestination (writer) - コンテナが PrintWriter をアダプタに渡すときに使用されるアペンダを追加します。
logger.warn ("Some message", true) - 優先度レベルが WARN のメッセージをログに記録しますが、ResourceBundle を使用しません。ブール値は、文字列がメッセージであり、キーではないことを示します。
logger.warn ("someKey") - 優先度レベルが WARN のメッセージをログに記録します。ResourceBundle では "someKey" を使用してルックアップします。
logger.info ("someKey", anObjArray) - 優先度レベルが INFO のメッセージをログに記録します。ResourceBundle では someKey を使用してテンプレートをルックアップし、空白を anObjArray の要素で埋めます。
logger.error (exception) - 優先度レベルが ERROR のメッセージを、このメソッドに例外 (Throwable) を渡すことによって、ログに記録します。このメソッドは、getMessage() を呼び出し、スタックトレースを組み込みます (Throwable を引数として取得するロギングメソッドは、すべてスタックトレースをログに記録します)。

com.bea.logging.LogContext

このクラスは、ロギングフレームワークの ILogger インスタンスの識別に必要な情報をカプセル化します。現在、LogContext クラスは、ログカテゴリ名、および en_US などのロケールをカプセル化します。このクラスは、ログマネージャ内の ILogger インスタンスをユニークに識別するための主キーです。

com.bea.logging.LogManager

このクラスのメソッドによって、ロギングフレームワークのコンフィグレーションが可能になり、ILogger インスタンスにアクセスできます。

使用するアダプタに対応するロギングツールキットを適切にコンフィグレーションできるように、ADK では、LogManager の configure() メソッドをコードリスト 5-5 に示す引数で実装しています。

表 5-2 configure() の引数
引数	説明
`strLogConfigFile`	アダプタのログコンフィグレーション情報が記述されているファイル。このファイルの場所は、クラスパスに含める必要がある。使用するアダプタのメイン JAR ファイルにインクルードして、そのアダプタの WAR および RAR ファイルにこのファイルがインクルードされるようにすることを推奨。このファイルは、`Log4j.dtd` に準拠する必要がある。`Log4j.dtd` ファイルは、WebLogic Integration の `Log4j.jarfile` にある。
`strRootLogContext`	アダプタのカテゴリ階層の論理ルート名。このサンプルアダプタの場合の値は、`BEA_WLS_SAMPLE_ADK`。
`strMessageBundleBase`	アダプタのメッセージバンドルの基本名。ADK では、メッセージバンドルを使用する必要がある。このサンプルアダプタの場合の値は、`BEA_WLS_SAMPLE_ADK`。
`locale`	ユーザの国と言語。ロギングツールキットでは、ロケールに基づいてカテゴリをさまざまな階層に構成する。たとえば、アダプタが `en_US` および `fr_CA` の 2 つのロケールをサポートする場合、ロギングツールキットでは、`en_US` 用と `fr_CA` 用の 2 つの階層を管理する。
`classLoader`	`LogManager` が `ResourceBundles` やログコンフィグレーションファイルなどのリソースをロードするときに使用する `ClassLoader`。

コンフィグレーションが完了すると、LogContext オブジェクトを指定することで、アダプタで使用する ILogger インスタンスを取得できます。

ADK では、ほとんどのログコンフィグレーションおよび設定が表示されません。com.bea.adapter.spi.AbstractManagedConnectionFactory クラスは、サービス接続のロギングツールキットをコンフィグレーションし、AbstractEventGenerator はイベント接続のロギングツールキットをコンフィグレーションします。さらに、ADK に用意されているクライアントコネクタインタフェース (Client Connector Interface : CCI) およびサービスプロバイダインタフェース (Service Provider Interface : SPI) の基本クラスは、すべて ILogger とこれに関連付けられた LogContext へのアクセス機能を備えています。

アダプタには、EIS に対する通信を確立するために使用するソケットレイヤなど、CCI/SPI レイヤをサポートするレイヤも含まれる場合があります。アダプタが適切な ILogger オブジェクトにアクセスする方法は、2 つあります。

CCI/SPI レイヤは、下位レイヤに LogContext オブジェクトを渡すことができる。ただし、この方法はオーバーヘッドが大きくなります。
CCI レイヤは、現在実行しているスレッドに対して、コード内の最も早い段階で LogContext を設定できる。ADK の com.bea.adapter.cci.ConnectionFactoryImpl クラスは、現在実行中のスレッドに対する LogContext を getConnection() メソッドに設定します。この getConnection() メソッドが、クライアントプログラムとアダプタの間の最初の接点になります。したがって、アダプタ内の下位のレイヤは、以下のコードを使用することにより、現在実行中のスレッドの LogContext に安全にアクセスできます。

コードリスト 5-7 現在のスレッドに対する LogContext にアクセスするためのコード

public static LogContext getLogContext(Thread t)
   throws IllegalStateException, IllegalArgumentException

また、LogManager には以下のような便利なメソッドがあります。

public static ILogger getLogger() throws IllegalStateException

このメソッドは、現在実行中のスレッドに対して ILogger を設定します。ただし、この方法には注意点が 1 つあります。下位レイヤには、LogContext または ILogger をメンバーとして格納しないでください。下位レイヤが、これらを LogManager から動的に取得するようにします。LogContext が現在実行中のスレッドに対して設定される前にこのメソッドが呼び出されると、IllegalStateException が送出されます。

ログメッセージのインターナショナライゼーションとローカライゼーション

インターナショナライゼーション (I18N) とローカライゼーション (L10N) は、ADK のロギングフレームワークの中心的な概念です。ILogger インタフェースで、ロギングに使用するすべてのメソッドは、デバッグメソッドを除き I18N を提供しています。この実装は Java インターナショナライゼーション標準に従い、ResourceBundle オブジェクトを使用して、ロケール固有のメッセージまたはテンプレートを格納します。Java 言語の I18N および L10N 標準の使用方法については、Sun Microsystems 社から優れたオンラインチュートリアルが提供されています。

マルチスレッドコンポーネントでのコンテキスト情報の保存

実際に運用されているシステムの多くは、複数のクライアントを同時に処理する必要があります。そのようなシステムの典型的なマルチスレッド実装では、スレッドごとに異なるクライアントを処理します。ロギングは、特に複雑な分散アプリケーションのトレースおよびデバッグに適しています。2 つのクライアント間のロギング出力を区別する一般的な方法は、クライアントごとに個別カテゴリをインスタンス化することです。ただし、この方法には欠点があります。カテゴリが増大し、これらを管理するオーバーヘッドが大きくなる点です。

より負荷の小さい方法は、同じクライアント対話で開始された各ログ要求に、ユニークな識別子でスタンプを設定することです。Neil Harrison 氏が、この方法を『Pattern Languages of Program Design 3』 (R. Martin、D. Riehle、F. Buschmann 編、Addison-Wesley、1997) の「Patterns for Logging Diagnostic Messages」で説明しています。

各要求にユニークな識別子でスタンプを設定するには、ユーザはコンテキスト情報を NDC (Nested Diagnostic Context) にプッシュします。ロギングツールキットには、NDC メソッドへのアクセスのための独立したインタフェースがあります。このインタフェースは、getNDCInterface() メソッドを使用して ILogger から取得されます。

NDC 出力は、XML コンフィグレーションファイル (%x 記号による) でオンになります。ログ要求が行われるたびに、適切なロギングフレームワークコンポーネントが、現在のスレッドに対する全 NDC スタックをログ出力に組み込みます。ユーザがこの処理に介入する必要はありません。ユーザの作業は、コード内のいくつかの決められた場所で push および pop メソッドを使用して、正しい情報を NDC に入力するだけです。

NDC は、使用するアダプタの CCI Interaction オブジェクト内でよく使用されます。

アダプタの開発

ロギング ツールキットの使い方