複数のログ処理APIをラップするシンプルなラッパーAPIです。 {@primary Simple wrapper API around multiple logging APIs.}

概要{@primary Overview}

このパッケージは複数のログ処理の実装を利用する可能性のあるサーバ上のアプリケーションのログ処理を行うためのAPIを提供します。デフォルトで以下のAPIをサポートします。 {@primary This package provides an API for logging in server-based applications that can be used around a variety of different logging implementations, including prebuilt support for the following:}

Apache Jakarta プロジェクトの Log4J (version 1.2 以降)。名前のついた各 Log インスタンスは対応する Log4J Logger に結び付けられます。
JDK 1.4 以降に含まれる JDK Logging API。名前のついた各 Log インスタンスは対応する java.util.logging.Logger インスタンスに結び付けられます。
Apache Avalon プロジェクトの LogKit。名前のついた各 Log インスタンスは対応する LogKit Logger に結び付けられます。
NoOpLog 実装。名前のついた各 Log インスタンスのログ出力は取り込まれるだけです(出力されません)
SimpleLog 実装。名前のついた各 Log インスタンスのログ出力を System.err に出力します。

{@primary

Log4J (version 1.2 or later) from Apache's Jakarta project. Each named Log instance is connected to a corresponding Log4J Logger.
JDK Logging API, included in JDK 1.4 or later systems. Each named Log instance is connected to a corresponding java.util.logging.Logger instance.
LogKit from Apache's Avalon project. Each named Log instance is connected to a corresponding LogKit Logger.
NoOpLog implementation that simply swallows all log output, for all named Log isntances.
SimpleLog implementation that writes all log output, for all named Log instances, to System.err.

}

クイックスタートガイド{@primary Quick Start Guide}

とにかく早く使い方を知りたい人のために、 (慣例により) 呼び元のクラス名をつけたロガーの宣言方法とその使い方の典型的な例を以下に示します: {@primary For those impatient to just get on with it, the following example illustrates the typical declaration and use of a logger that is named (by convention) after the calling class:}

    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 に出力されます。従って、アプリケーションのログ処理の設定方法を理解するには、このページのこれ以降の記述を読む必要があります。 {@primary Unless you configure things differently, all log output will be written to System.err. Therefore, you really will want to review the remainder of this page in order to understand how to configure logging for your application.}

Commons Logging パッケージの設定 {@primary Configuring the Commons Logging Package}

`LogFactory` の実装を選択する {@primary Choosing A `LogFactory` Implementation}

アプリケーション内での手順として、まずは Log インスタンスを生成する際に使用される LogFactory オブジェクトへの参照を取得することになります。通常はスタティックメソッドの getFactory() を呼ぶことで行います。このメソッドはアプリケーションで使用したい LogFactory の実装クラスの名称を選択するための以下の検索アルゴリズムを実装しています: {@primary From an application perspective, the first requirement is to retrieve an object reference to the LogFactory instance that will be used to create Log instances for this application. This is normally accomplished by calling the static getFactory() method. This method implements the following discovery algorithm to select the name of the LogFactory implementation class this application wants to use:}

org.apache.commons.logging.LogFactory という名称のシステムプロパティをチェックします。
JDK 1.3 の JARファイル仕様のサービスプロバイダの機能 (詳細は http://java.sun.com/j2se/1.3/ja/docs/ja/guide/jar/jar.html を参照して下さい) を使用して META-INF/services/org.apache.commons.logging.LogFactory という名称のリソースを検索し、最初にみつかった行に含まれるクラス名を実装クラス名とみなします。
アプリケーション内で有効なクラスパスから commons-logging.properties という名称のプロパティファイルを検索し org.apache.commons.logging.LogFactory という名称のプロパティの値を実装クラス名とします。
それ以外の場合は後の章で説明されるデフォルトの(ファクトリ)実装を使います。

{@primary

Check for a system property named org.apache.commons.logging.LogFactory.
Use the JDK 1.3 JAR Services Discovery mechanism (see http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html for more information) to look for a resource named META-INF/services/org.apache.commons.logging.LogFactory whose first line is assumed to contain the desired class name.
Look for a properties file named commons-logging.properties visible in the application class path, with a property named org.apache.commons.logging.LogFactory defining the desired implementation class name.
Fall back to a default implementation, which is described further below.

}

commons-logging.properties ファイルが見つかった場合、ファイル内に設定されているすべてのプロパティはインスタンス化した LogFactory インスタンスに属性として設定されます。 {@primary If a commons-logging.properties file is found, all of the properties defined there are also used to set configuration attributes on the instantiated LogFactory instance.}

一度、実装クラス名が選択されると、対応するクラスがロードされます。ロードするのは (それが1つなら) 現在のスレッドのコンテキストクラスローダ、そうでなければ LogFactory クラス自身をロードしたクラスローダです。これによって、(サーブレットコンテナのような) 複数のクラスローダが存在する環境で、単一の commons-logging.jar を共有できるようになりますが、望むならば、各Webアプリケーションが独自の LogFactory 実装を使うようにもできます。その場合、このクラスのインスタンスが1つ作成され、クラスローダ毎にキャッシュされます。 {@primary Once an implementation class name is selected, the corresponding class is loaded from the current Thread context class loader (if there is one), or from the class loader that loaded the LogFactory class itself otherwise. This allows a copy of commons-logging.jar to be shared in a multiple class loader environment (such as a servlet container), but still allow each web application to provide its own LogFactory implementation, if it so desires. An instance of this class will then be created, and cached per class loader.}

デフォルトの `LogFactory` 実装 {@primary The Default `LogFactory` Implementation}

Logging Package API には他の実装クラス名が見つからなかった場合に適用されるデフォルトの LogFactory 実装クラス (org.apache.commons.logging.impl.LogFactoryImpl) があります。このクラスの主な目的は getInstance() メソッド呼び出しで Log インスタンスを生成して返すことです。デフォルト実装は以下のルールに従います。 {@primary The Logging Package APIs include a default LogFactory implementation class ( org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no other implementation class name can be discovered. Its primary purpose is to create (as necessary) and return Log instances in response to calls to the getInstance() method. The default implementation uses the following rules:}

同じ名称の 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 もチェックします)。
- アプリケーションクラスパス内に Log4J ログシステムが存在する場合には、対応するラッパークラス (Log4JLogger)を使用します。
- アプリケーションが JDK 1.4 上で動作している場合には、対応するラッパークラス (Jdk14Logger)を使用します。
- それ以外の場合はデフォルトのシンプルログラッパー(SimpleLog)を使用します。
指定された名称のクラスをロードします。スレッドコンテキストクラスローダがあればそこから、それ以外の場合は LogFactory クラス自身をロードしたクラスローダからロードします。
指定された名称を単一の引数として、選択された Log 実装クラスをインスタンス化します。

{@primary

At most one Log instance of the same name will be created. Subsequent getInstance() calls to the same LogFactory instance, with the same name or Class parameter, will return the same Log instance.
When a new Log instance must be created, the default LogFactory implementation uses the following discovery process is used:
- Look for a configuration attribute of this factory named org.apache.commons.logging.Log (for backwards compatibility to pre-1.0 versions of this API, an attribute org.apache.commons.logging.log is also consulted)..


Load the class of the specified name from the thread context class
    loader (if any), or from the class loader that loaded the
    LogFactory class otherwise.
Instantiate an instance of the selected Log
    implementation class, passing the specified name as the single
    argument to its constructor.

}

このデフォルト実装に関する詳細な設定の情報は
SimpleLog の JavaDoc を参照してください。
{@primary See the SimpleLog JavaDocs for detailed
configuration information for this default implementation.}


内部で使用するログシステムの設定
{@primary Configuring the Underlying Logging System}


基本的な原則としてユーザは内部で使用するログシステムの設定に関して全て責任を持つ必要があります。
Commons-logging は設定された内容を変更しません。
{@primary The basic principle is that the user is totally responsible for the 
configuration of the underlying logging system. 
Commons-logging should not change the existing configuration.}

個々の Log 実装で固有の設定プロパティをサポートする場合があります。
それについては該当する実装クラスの (JavaDoc等の) 説明に記述されています。
{@primary Each individual Log implementation may
support its own configuration properties.  These will be documented in the
class descriptions for the corresponding implementation class.}

最後に、ログ処理環境全体に適用する外部設定ファイルが必要な
Log 実装もあります (Log4Jなど)。
そうしたファイルについては実際に使用されるログ出力機能のルールに従って用意してください。
{@primary Finally, some Log implementations (such as the one for Log4J)
require an external configuration file for the entire logging environment.
This file should be prepared in a manner that is specific to the actual logging
technology being used.}

Logging Package API の使用方法
{@primary Using the Logging Package APIs}

アプリケーション内で Logging Package API を利用する場合には、以下の手順にて行ってください:
{@primary Use of the Logging Package APIs, from the perspective of an application
component, consists of the following steps:}

ファクトリメソッド LogFactory.getInstance(String name)
    を呼び、org.apache.commons.logging.Log インスタンスへの参照を取得します。
    用途別に違ったロガーをアプリケーション内に持つことができます。
    サーバアプリケーションでは通常、主なコンポーネント毎に個別のログインスタンスを使用します。
メソッド
    (debug()、info()、warn()、error、fatal())
    を適宜呼ぶことで、(対応したログレベルが有効な場合) メッセージのログ出力を行います。

{@primary 
Acquire a reference to an instance of
    org.apache.commons.logging.Log, by calling the
    factory method
    
    LogFactory.getInstance(String name).  Your application can contain
    references to multiple loggers that are used for different
    purposes.  A typical scenario for a server application is to have each
    major component of the server use its own Log instance.
Cause messages to be logged (if the corresponding detail level is enabled)
    by calling appropriate methods (debug(), info(),
    warn(), error, and fatal()).
}

使いやすくするために LogFactory は典型的な2つのステップを一体化したスタティックメソッド
getLog() も提供しています。
{@primary For convenience, LogFactory also offers a static method
getLog() that combines the typical two-step pattern:}

  Log log = LogFactory.getFactory().getInstance("Foo");

は以下の単独メソッドに置き換えることができます。{@primary into a single method call:}
  Log log = LogFactory.getLog("Foo");


例えばアプリケーション内で Log インスタンスを初期化して使用する場合、以下のテクニックが使えます。
{@primary For example, you might use the following technique to initialize and
use a Log instance in an application component:}
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);
    ...
  }

}


{@primary import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class MyComponent {

  protected static Log log =
    LogFactory.getLog("my.component");

  // Called once at startup time
  public void start() {
    ...
    log.info("MyComponent started");
    ...
  }

  // Called once at shutdown time
  public void stop() {
    ...
    log.info("MyComponent stopped");
    ...
  }

  // Called repeatedly to process a particular argument value
  // which you want logged if debugging is enabled
  public void process(String value) {
    ...
    // Do the string concatenation only if logging is enabled
    if (log.isDebugEnabled())
      log.debug("MyComponent processing " + value);
    ...
  }

}
}

@translator 日置 聡
@editor 高橋 達男
@status completion
@update 2004/04/08

概要{@primary Overview}

クイックスタートガイド{@primary Quick Start Guide}

Commons Logging パッケージの設定 {@primary Configuring the Commons Logging Package}

LogFactory の実装を選択する {@primary Choosing A LogFactory Implementation}

デフォルトの LogFactory 実装 {@primary The Default LogFactory Implementation}

内部で使用するログシステムの設定 {@primary Configuring the Underlying Logging System}

Logging Package API の使用方法 {@primary Using the Logging Package APIs}

`LogFactory` の実装を選択する {@primary Choosing A `LogFactory` Implementation}

デフォルトの `LogFactory` 実装 {@primary The Default `LogFactory` Implementation}