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

ドキュメントのダウンロード

サイトマップ

用語集

検索

e-docs > WebLogic Integration > AI トピック > アダプタの開発 > ロギングツールキットの使い方

アダプタの開発

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

ロギングは、アダプタコンポーネントに不可欠な機能です。一般的にアダプタは、複数のアプリケーションの統合に使用され、データの処理時にエンドユーザとは対話しません。フロントエンドコンポーネントの動作とは異なり、エラーや警告状況が発生した場合も、処理を停止して、エンドユーザの応答を待つことはありません。

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

この章の内容は以下のとおりです。

ロギングツールキット

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

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

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 は、ルートカテゴリの子孫になっています。

ROOT CATEGORY
  |
  |->BEA_WLS_SAMPLE_ADK
      |
      |->BEA_WLA_SAMPLE.ADK.DesignTime

ルートカテゴリはカテゴリ階層の最上位にあり、名前で削除あるいは検索することができません。

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

メッセージ優先度

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

ロギングツールキットでは、メッセージに対して 5 つの優先度をサポートしています。これらの優先度は、優先度の高い順に表 5-1 にリストされます。

表5-1 ロギングツールキットの優先度

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

BEA_WLS_SAMPLE_ADK カテゴリには下記の子要素があるので、その重要度は「WARN」となっています。

<priority value='WARN' class='com.bea.logging.LogPriority'/>

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

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

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

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

メッセージアペンダ

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

コンソール
ファイル
リモートソケットサーバ
NT イベントロガー
リモート UNIX Syslog デーモン

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

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

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

注意: この場合、さらにコンソールアペンダを直接 C に追加すると、同じメッセージが 2 回（C からとルートから）コンソールに表示されます。ルートカテゴリが、常にコンソールにログを出力するためです。

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

コードリスト 5-1 WebLogic Server ログに対するアペンダを示すサンプルコード

<!--
  WeblogicAppender がログ出力を Weblogic ログに送る。Weblogic 外で稼働する場合、
  アペンダはメッセージを System.out に書き出す
  -->
  <appender name="WebLogicAppender"
     class="com.bea.logging.WeblogicAppender"/>
</appender>

メッセージレイアウト

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

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

AUDIT 21 May 2001 11:00:57,109 BEA_WLS_SAMPLE_ADK - admin opened connection to EIS

このパターンの各パラメータの意味は以下のとおりです。

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

「-」の後ろのテキストは、メッセージ内容です。

コンポーネントの結合

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

コードリスト 5-2 新しいログカテゴリを宣言するサンプル XML コード

<!-
 
重要!!!アダプタのルート カテゴリ、これを一意のものにすることで、
他のアダプタがカテゴリにロギングされるのを防ぐ。
-->
 
<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>

注意: クラスは com.bea.logging.LogCategory と指定します。

ロギングの設定方法

注意: 次の手順は、GenerateAdapterTemplate ユーティリティを実行して開発環境の複製が作成されていることを前提としています。このユーティリティの詳細については、カスタム開発環境の作成を参照してください。

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

アダプタで使用されるすべての基本コンポーネントを確認します。たとえば、アダプタに 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> 要素内の指定により、メッセージフォーマットが識別されます。

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

コードリスト 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/eventrouter/web-inf/web.xml : AbstractEventGenerator が、この基本コンフィグレーションファイルに入力されたロギング情報を使用して、初期化時にログフレームワークのコンフィグレーションを行います。
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 サンプルアダプタの場合、関連付けられたコンフィグレーションファイルのパス名は次のようになります。

WLI_HOME/adapters/dbms/src/rar/META-INF/ra.xml

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

ロギングフレームワークの基本コンセプトを理解した上で、さらにロギングツールキットに用意されている 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 のメッセージを、someKey によってテンプレートを ResourceBundle でルックアップし、ブランクを anObjArray の要素で埋めてログに記録します。
logger.error (exception) －優先度レベルが ERROR のメッセージを、このメソッドに例外（Throwable）を渡すことによってログに記録します。メソッドは、getMessage() を呼び出し、スタックトレースを組み込みます。（Throwable を引数として取るロギングメソッドは、すべてスタックトレースをログに記録します。）

com.bea.logging.LogContext

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

com.bea.logging.LogManager

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

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

コードリスト 5-5 ロギングツールキットのコンフィグレーション用のサンプルコード

public static LogContext
   configure(String strLogConfigFile,
             String strRootLogContext,
             String strMessageBundleBase,
             Locale locale,
              ClassLoader classLoader)

表 5-2 は、configure() によって渡される引数の説明です。

表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 用に 1 つずつ、2 つの階層を管理する。
classLoader	LogManager が ResourceBundles やログコンフィグレーションファイルなどのリソースをロードするときに使用する ClassLoader。

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

コードリスト 5-6 LogContext オブジェクトを指定するサンプルコード

LogContext logContext = new LogContext("BEA_WLS_SAMPLE_ADK",   java.util.Locale.US);

ILogger logger = LogManager.getLogger(logContext); logger.debug("I'm logging now!");

ADK では、ほとんどのログコンフィグレーションおよび設定は自動で行われます。com.bea.adapter.spi.AbstractManagedConnectionFactory クラスは、サービスアダプタのロギングツールキットをコンフィグレーションし、AbstractEventGenerator はイベントアダプタのロギングツールキットをコンフィグレーションします。さらに、ADK に用意されているクライアントコネクタインタフェース（CCI）およびサービスプロバイダインタフェース（SPI）の基本クラスはすべて、ILogger およびその関連付けられた LogContext へのアクセス機能を備えています。

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

CCI/SPI レイヤは、下位レイヤに LogContext オブジェクトを渡すことができます。この方法は、余分なオーバーヘッドがかかります。
CCI レイヤは、現在実行しているスレッドに対して、コード内の可能な最も近い場所で LogContext を設定できます。ADK の com.bea.adapter.cci.ConnectionFactoryImpl クラスは、現在実行中のスレッドに対して、getConnection() メソッド中に LogContext を設定します。この 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」で説明しています。

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

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

コードリスト 5-8 サンプルコード

public void someAdapterMethod(String aClient) {
    ILogger logger = getLogger();
  INestedDiagnosticContext ndc = logger.getNDCInterface();
  // 全ログ メッセージについてこのクライアント名を追跡する
  ndc.push("User name=" + aClient);
  // メソッド本体 ・・・
  ndc.pop();
  }

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