|
||||||||||
| 前のパッケージ 次のパッケージ | フレームあり フレームなし | |||||||||
参照:
説明
| インタフェースの概要 | |
| Log | ログ処理の API を抽象化したシンプルなログ処理のインタフェースです。 |
| クラスの概要 | |
| LogFactory | Log インスタンスを生成するファクトリです。 |
| LogSource | 推奨されていません。 LogFactory を代わりに使用してください。
|
| 例外の概要 | |
| LogConfigurationException | 該当するファクトリメソッドにて適切な LogFactory または
Log のインスタンスが生成出来なかったときにのみ投げられる例外です。
|
複数のログ処理APIをラップするシンプルなラッパーAPIです。
このパッケージは複数のログ処理の実装を利用する可能性のある サーバ上のアプリケーションのログ処理を行うためのAPIを提供します。 デフォルトで以下のAPIをサポートします。
java.util.logging.Logger
インスタンスに結び付けられます。Logger に結び付けられます。とにかく早く使い方を知りたい人のために、 (慣例により) 呼び元のクラス名をつけたロガーの宣言方法とその使い方の典型的な例を以下に示します:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
public class Foo {
static Log log = LogFactory.getLog(this.class);
public void foo() {
...
try {
if (log.isDebugEnabled()) {
log.debug("About to do something to object " + name);
}
name.bar();
} catch (IllegalStateException e) {
log.error("Something bad happened to " + name, e);
}
...
}
何も設定を行わない場合、すべてのログは System.err に出力されます。 従って、アプリケーションのログ処理の設定方法を理解するには、このページのこれ以降の記述を読む必要があります。
LogFactory の実装を選択する
アプリケーション内での手順として、まずは
Log インスタンスを生成する際に使用される
LogFactory オブジェクトへの参照を取得することになります。
通常はスタティックメソッドの getFactory() を呼ぶことで行います。
このメソッドはアプリケーションで使用したい LogFactory
の実装クラスの名称を選択するための以下の検索アルゴリズムを実装しています:
org.apache.commons.logging.LogFactory
という名称のシステムプロパティをチェックします。META-INF/services/org.apache.commons.logging.LogFactory
という名称のリソースを検索し、最初にみつかった行に含まれるクラス名を実装クラス名とみなします。commons-logging.properties
という名称のプロパティファイルを検索し org.apache.commons.logging.LogFactory
という名称のプロパティの値を実装クラス名とします。commons-logging.properties ファイルが見つかった場合、
ファイル内に設定されているすべてのプロパティはインスタンス化した
LogFactory インスタンスに属性として設定されます。
一度、実装クラス名が選択されると、対応するクラスがロードされます。ロードするのは (それが1つなら)
現在のスレッドのコンテキストクラスローダ、そうでなければ LogFactory
クラス自身をロードしたクラスローダです。
これによって、(サーブレットコンテナのような) 複数のクラスローダが存在する環境で、
単一の commons-logging.jar を共有できるようになりますが、
望むならば、各Webアプリケーションが独自の LogFactory 実装を使うようにもできます。
その場合、このクラスのインスタンスが1つ作成され、クラスローダ毎にキャッシュされます。
LogFactory 実装
Logging Package API には他の実装クラス名が見つからなかった場合に適用されるデフォルトの
LogFactory 実装クラス
(org.apache.commons.logging.impl.LogFactoryImpl)
があります。
このクラスの主な目的は getInstance() メソッド呼び出しで
Log インスタンスを生成して返すことです。
デフォルト実装は以下のルールに従います。
Log インスタンスは多くても1つしか生成されません。
2回目以降、同じ LogFactory インスタンスに対して、
同じ名称または同じ Class 引数で
getInstance() を呼んだ場合、同じ Log
インスタンスを返します。Log インスタンスを生成する必要がある場合、デフォルトの
LogFactory 実装では以下の検索処理を行います。
org.apache.commons.logging.Log
という名称の属性を探します
(pre-1.0 との下位互換のため org.apache.commons.logging.log もチェックします)。org.apache.commons.logging.Log という名称のシステムプロパティを探します
(pre-1.0 との下位互換のため org.apache.commons.logging.log もチェックします)。LogFactory クラス自身をロードしたクラスローダからロードします。Log 実装クラスをインスタンス化します。このデフォルト実装に関する詳細な設定の情報は SimpleLog の JavaDoc を参照してください。
基本的な原則としてユーザは内部で使用するログシステムの設定に関して全て責任を持つ必要があります。 Commons-logging は設定された内容を変更しません。
個々の Log 実装で固有の設定プロパティをサポートする場合があります。 それについては該当する実装クラスの (JavaDoc等の) 説明に記述されています。
最後に、ログ処理環境全体に適用する外部設定ファイルが必要な
Log 実装もあります (Log4Jなど)。
そうしたファイルについては実際に使用されるログ出力機能のルールに従って用意してください。
アプリケーション内で Logging Package API を利用する場合には、以下の手順にて行ってください:
debug()、info()、warn()、error、fatal())
を適宜呼ぶことで、(対応したログレベルが有効な場合) メッセージのログ出力を行います。使いやすくするために LogFactory は典型的な2つのステップを一体化したスタティックメソッド
getLog() も提供しています。
Log log = LogFactory.getFactory().getInstance("Foo");
は以下の単独メソッドに置き換えることができます。
Log log = LogFactory.getLog("Foo");
例えばアプリケーション内で Log インスタンスを初期化して使用する場合、以下のテクニックが使えます。
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
public class MyComponent {
protected static Log log =
LogFactory.getLog("my.component");
// 起動時に一度呼ばれる
public void start() {
...
log.info("MyComponent started");
...
}
// シャットダウン時に一度呼ばれる
public void stop() {
...
log.info("MyComponent stopped");
...
}
// 指定した引数の値を処理するために繰り返し呼ばれる。
// デバッグの設定が有効な場合だけ引数の値のログ出力を行なう。
public void process(String value) {
...
// ログ処理が有効な場合にのみ文字列の連結を行う
if (log.isDebugEnabled())
log.debug("MyComponent processing " + value);
...
}
}
|
||||||||||
| 前のパッケージ 次のパッケージ | フレームあり フレームなし | |||||||||