モジュール java.logging
パッケージ java.util.logging

クラスLogger

java.lang.Object
java.util.logging.Logger
public class Logger extends Object
Loggerオブジェクトは、特定のシステム・コンポーネントやアプリケーション・コンポーネントのメッセージをロギングするために使用されます。 ロガーの命名は通常、ドットで区切られた階層化された名前空間を使って行われます。 ロガーの名前はどのような文字列でもかまいませんが、通常は、java.netやjavax.swingなど、ロギング対象のコンポーネントのパッケージ名やクラス名に基づいた名前にすべきです。 さらに、Loggerの名前空間に格納されない「匿名」のLoggerを作成することも可能となっています。

Loggerオブジェクトを取得するには、getLoggerファクトリ・メソッドのいずれかを呼び出します。 これらは、新しいLoggerを作成するか、既存の適したLoggerを返します。 getLoggerファクトリ・メソッドのいずれかによって返されるLoggerは、Loggerに対する強い参照が保持されなければ、いつでもガベージ・コレクトされる可能性があると理解することが重要です。

ログ・メッセージは登録されたHandlerオブジェクトに転送されます。このオブジェクトは、コンソール、ファイル、OSログなどさまざまな出力先にメッセージを転送できます。

各Loggerは、Loggerの名前空間にある既存の上位クラスにもっとも近い「親」Loggerを追跡します。

各Loggerには「Level」が関連付けられます。 これは、このロガーの処理対象となる最小のLevelを表します。 ロガーのレベルがnullに設定されている場合、その有効レベルはその親から継承され、親から再帰的に取得される可能性があり、ツリーの上位まで続きます。

ログ・レベルは、LogManagerクラスで説明しているように、ロギング構成ファイルのプロパティに基づいて構成できます。 ただしそれは、Logger.setLevelメソッドを呼び出して動的に変更することもできます。 ロガーのレベルが変更されると、そのレベルとしてnullを持つ子ロガーは親からその有効レベルを継承するため、変更も子ロガーに影響する可能性があります。

ロギング呼出しが行われるたびに、Loggerはまず、そのロガーの実効ログ・レベルに基づく要求レベル(SEVEREやFINEなど)の低コストなチェックを実行します。 要求レベルがログ・レベルよりも低い場合、ロギング呼出しはすぐに復帰します。

この初期テスト(低コストのテスト)にパスすると、Loggerは、LogRecordを割り当ててロギング・メッセージを記述します。 次に、それは、Filterが存在する場合にはそれを呼び出し、そのレコードを発行すべきかどうかについて、より詳しいチェックを行います。 それにパスした場合、それは、そのLogRecordを自身の出力Handlerに発行します。 デフォルトでは、ロガーは親のHandlerにも発行します。これが、ツリーの上方に向けて再帰的に繰り返されます。

各Loggerには、関連付けられたResourceBundleがある場合があります。 ResourceBundleは、getLogger(java.lang.String, java.lang.String)ファクトリ・メソッドを使用して名前で指定するか、またはsetResourceBundleメソッドを使用して値で指定できます。 このバンドルはロギング・メッセージをローカライズするために使用されます。 Loggerが独自のResourceBundleまたはリソース・バンドル名を持たない場合、ResourceBundleまたはリソース・バンドル名を親から継承し、ツリーの上方に向けて再帰的に繰り返されます。

ロガーの出力メソッドのほとんどは、「msg」引数を取ります。 このmsg引数には、生の値、ローカリゼーション・キーのいずれかを指定できます。 書式設定時に、ロガーがローカリゼーションResourceBundleを持って(または継承して)おり、そのResourceBundleにメッセージ文字列のマッピングがある場合、メッセージ文字列はローカライズされた値に置き換えられます。 それ以外の場合は、元のmsg文字列が使用されます。 フォーマッタは通常、java.text.MessageFormatスタイルのフォーマットを使ってパラメータを書式設定するため、たとえば、フォーマット文字列「{0} {1}」は、2つのパラメータを文字列として書式設定します。

一連のメソッドは、「msg」引数の代わりに「msgSupplier」をとります。 これらのメソッドは、Supplier<String>関数をとり、この関数はメッセージが実際に実効ログ・レベルに基づいて、ログに記録されるときにのみ、目的のログ・メッセージを構築するために呼び出されるため、不要なメッセージの構築がなくなります。 たとえば、開発者が、文字列を受け付けるバージョンで、診断用のシステム正常性ステータスをログに記録したい場合、コードは次のようなものになります。 



  class DiagnosisMessages {
    static String systemHealthStatus() {
      // collect system health information
      ...
    }
  }
  ...
  logger.log(Level.FINER, DiagnosisMessages.systemHealthStatus());
上のコードでは、ログ・レベルFINERが無効にされている場合でも、正常性ステータスが不必要に収集されます。 下のようなサプライヤ受け付けバージョンでは、ログ・レベルFINERが有効にされている場合にのみ、ステータスが収集されます。 


  logger.log(Level.FINER, DiagnosisMessages::systemHealthStatus);

ロガーがResourceBundleを検索する場合、まずバンドルがsetResourceBundleを使用して指定されているかどうか、次に、getLoggerファクトリ・メソッドによって、リソースバンドル名が指定されているかどうかのみを調べます。 ResourceBundleまたはリソース・バンドル名が見つからない場合は、親ツリーから継承したもっとも近いResourceBundleまたはリソース・バンドル名を使用します。
ResourceBundleが継承されているか、setResourceBundleメソッドによって指定されている場合、そのResourceBundleが使われます。 そうでない場合に、ロガーがリソース・バンドル名のみを持つか、継承している場合は、ロギング時に、デフォルトのロケールを使用して、そのリソース・バンドル名をResourceBundleオブジェクトにマッピングします。
リソース・バンドル名をResourceBundleオブジェクトにマッピングする際に、ロガーはまずスレッドのコンテキスト・クラス・ローダーを使用して、指定されたリソース・バンドル名をResourceBundleにマッピングします。 スレッド・コンテキスト・クラス・ローダーがnullの場合、代わりにシステム・クラス・ローダーを試します。 ResourceBundleがまだ見つからない場合、getLoggerファクトリ・メソッドの最初の呼出し元のクラス・ローダーを使用します。

ローカリゼーションを含むフォーマット処理は、通常Formatterを呼び出す出力Handlerを担当します。

フォーマット処理は同期的に行う必要がないことに注意してください。 それは、LogRecordが外部シンクに実際に書き込まれるまで遅延できます。

ロギング・メソッドは、次の5つの主なカテゴリに分類されます。

  • ログ・レベル、メッセージ文字列、およびそのメッセージ文字列への任意のパラメータを取得するlogメソッドのセット

  • logメソッドに類似するが、明示的なソース・クラス名とメソッド名も取得するlogpメソッドのセット(logpは「log precise」の略)

  • logpメソッドに類似するが、ログ・メッセージのローカライズに使用するための明示的なリソース・バンドル・オブジェクトもとるlogrbメソッドのセット(logrbは「log with resource bundle」の略)があります。

  • メソッドのエントリ(enteringメソッド)、メソッドの復帰(exitingメソッド)、および例外のスロー(throwingメソッド)を追跡するための簡易メソッド

  • 最後に、開発者がただ単純な文字列を特定のログ・レベルでロギングする、といった非常に単純な場合に使用するための、一連の簡易メソッドが存在する。 これらのメソッドは、「severe」、「warning」、「info」など、標準のLevel名にちなんだ名前を持ち、メッセージ文字列を単一の引数として取る。

明示的なソース名とメソッド名を取らないメソッドの場合、Loggingフレームワークは「最善の努力」を払って、どのクラスとメソッドがそのロギング・メソッドを呼び出したのかを判定します。 ただし、自動的に推測されたこの情報は概略に過ぎない(それどころか完全な間違いである可能性さえある)ことを理解しておく必要があります。 仮想マシンは、JIT処理の際に大規模な最適化を行うことが許されており、スタック・フレームをすべて削除する可能性があるため、呼出しクラスとメソッドを確実に検出することは不可能となっています。

Loggerのすべてのメソッドは、マルチスレッド・セーフです。

サブクラス化に関する情報: LogManagerクラスが名前付きLoggerの独自実装を名前空間内の任意の位置に提供する可能性があることに注意してください。 したがって、Loggerのすべてのサブクラスは、(それらが別の新しいLogManagerクラスとともに実装されたのでないかぎり)、忘れずにLogManagerクラスからLoggerインスタンスを取得し、そのインスタンスに「isLoggable」や「log(LogRecord)」などのオペレーションを委譲すべきです。 すべてのロギング出力を横取りするためにサブクラスが行う必要があるのは、log(LogRecord)メソッドのオーバーライドだけであることに注意してください。 ほかのロギング・メソッドはすべて、このlog(LogRecord)メソッドへの呼び出しとして実装されています。

導入されたバージョン:
1.4