クラスLogManager

java.lang.Object
java.util.logging.LogManager
public class LogManager extends Object
Loggerとログ・サービスの共有状態のセットを管理するために使用される単一のグローバルLogManagerオブジェクトがあります。

このLogManagerには次の機能があります。

  • Loggerオブジェクトの階層化された名前空間を管理する。 名前付きLoggerはすべて、この名前空間内に格納される。
  • ログ制御のプロパティのセットを管理する。 これらは単にキーと値のペアである。Handlerやその他のロギング・オブジェクトはこれらを使ってそれ自体を構成できる。

グローバルLogManagerオブジェクトは、LogManager.getLogManager()を使って取得できます。 このLogManagerオブジェクトはクラスの初期化中に作成され、その後は変更できません。

LogManagerクラスは、起動時にjava.util.logging.managerシステム・プロパティを使用して配置されます。

LogManagerの構成

LogManagerは、LogManagerの初期化中にreadConfiguration()メソッドを介してロギング構成を初期化します。 デフォルトでは、LogManagerデフォルト構成が使用されます。 LogManagerによって読み取られるロギング構成は、「プロパティ・ファイル」形式である必要があります。

LogManagerは、readConfiguration()メソッドで指定されているように、初期構成を制御できる2つのオプションのシステム・プロパティを定義します:

  • java.util.logging.config.class
  • java.util.logging.config.file

これらの2つのシステム・プロパティは、コマンドラインで"java"コマンドに指定することも、JNI_CreateJavaVMに渡されるシステム・プロパティ定義として指定することもできます。

ロガーおよびハンドラのpropertiesには、ハンドラまたはロガーのドット区切りの名前で始まる名前が含まれます。
グローバル・ログのプロパティには次のものがあります。

  • handlersプロパティ これは、空白で区切られたハンドラ・クラスのクラス名のリストを定義して、ルートLogger (""という名前のLogger)のハンドラとしてロードし登録する。 各クラス名は、デフォルト・コンストラクタを持つHandlerクラスのものでなければいけません。 これらのHandlerは初回使用時に遅延作成されるので注意してください。
  • <ロガー>.handlersプロパティ。 これは、ロードし、指定されたロガーのハンドラとして登録すべきハンドラ・クラスのクラス名の、空白またはカンマで区切られたリストを定義します。 各クラス名は、デフォルト・コンストラクタを持つHandlerクラスのものでなければいけません。 これらのHandlerは初回使用時に遅延作成されるので注意してください。
  • プロパティ"<logger>.handlers.ensureCloseOnReset"。 ブール値を定義します。 "<logger>.handlers"が定義されていないか空の場合、このプロパティは無視されます。 それ以外の場合は、デフォルトでtrueになります。 値がtrueの場合、ロガーに関連付けられたハンドラは、reset()および停止時にクローズされることが保証されます。 これは、構成で"<logger>.handlers.ensureCloseOnReset=false"を明示的に設定することでオフにできます。 このプロパティをオフにすると、reset()がコールされる前にロガーがガベージ・コレクションを受ける可能性があるため、reset()でハンドラがクローズされないため、リソース・リークが発生するリスクがあります。 その場合、ロガーがガベージ・コレクションされる前にハンドラが閉じられるようにするのは、アプリケーションの責任です。
  • <logger>.useParentHandlersプロパティ。 これはboolean値を定義します。 すべてのロガーはデフォルトで、ロギング・メッセージをそれ自体で処理するだけでなく、その親の呼び出しも行います。その結果、メッセージがルート・ロガーによっても処理されることがよくあります。 このプロパティをfalseに設定した場合、このロガーのHandlerを構成する必要があります。そうしないと、ロギング・メッセージが配信されません。
  • configプロパティ このプロパティは、任意の構成コードを実行できるようにすることを目的とする。 このプロパティは、空白またはカンマで区切られたクラス名リストを定義します。 各名前付きクラスに対して新しいインスタンスが作成される。 各クラスのデフォルト・コンストラクタは、ロガー・レベルの設定、ハンドラの追加、フィルタの追加など、任意のコードを実行することでロギング構成を更新できます。

LogManagerの構成中にロードされるクラスはすべて、ユーザー・クラス・パス上で検索される前にまずシステム・クラス・パス上で検索されることに注意してください。 これにはLogManagerクラス、すべてのconfigクラス、すべてのhandlerクラスが含まれます。

Loggerは、そのドットで区切られた名前に基づいて、ネーミング階層へと構造化されます。 その結果、「a.b.c」は「a.b」の子になりますが、「a.b1」および「a.b2」はピアになります。

名前が「.level」で終わるプロパティはすべて、Loggerのログ・レベルを定義しているとみなされます。 したがって、「foo.level」は「foo」と呼ばれるロガー、およびネーミング階層にあるその子のログ・レベルを再帰的に定義します。 ログ・レベルは、プロパティ・ファイルで定義した順に適用されます。 したがって、ツリー内の子ノードに対するレベルの設定は親に対する設定のあとに行う必要があります。 プロパティ名「.level」を使えば、ツリーのルートのレベルを設定できます。

LogManagerオブジェクトのすべてのメソッドはマルチ・スレッドに対して安全です。

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

  • フィールドのサマリー

    フィールド
    修飾子と型
    フィールド
    説明
    static final String
    LOGGING_MXBEAN_NAME
    ロギング機能の管理インタフェースのObjectNameの文字列表現。

  • コンストラクタのサマリー

    コンストラクタ
    修飾子
    コンストラクタ
    説明
    protected
    LogManager()
    protectedコンストラクタです。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    LogManager
    addConfigurationListener(Runnable listener)
    ロギング構成が読み取られるたびに起動する構成リスナーを追加します。
    boolean
    addLogger(Logger logger)
    名前付きロガーを追加します。
    void
    checkAccess()
    削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
    このメソッドは当初、ロギング構成を変更するために現在のコンテキストが信頼できることをチェックしました。
    Logger
    getLogger(String name)
    名前付きロガーを検出するメソッドです。
    Enumeration<String>
    getLoggerNames()
    既知のロガーの名前の列挙を返します。
    static LoggingMXBean
    getLoggingMXBean()
    非推奨。
    java.util.logging.LoggingMXBeanは非推奨され、java.lang.management.PlatformLoggingMXBeanに置き換えられました。
    static LogManager
    getLogManager()
    グローバルなLogManagerオブジェクトを返します。
    String
    getProperty(String name)
    ログのプロパティの値を返します。
    void
    readConfiguration()
    ロギング構成を読み取り、初期化します。
    void
    readConfiguration(InputStream ins)
    指定された入力ストリームからロギング構成を読み取り、初期化します。
    void
    removeConfigurationListener(Runnable listener)
    以前に登録した構成リスナーを削除します。
    void
    reset()
    ログの構成をリセットします。
    void
    updateConfiguration(InputStream ins, Function<String, BiFunction<String,String,String>> mapper)
    ロギング構成を更新します。
    void
    updateConfiguration(Function<String, BiFunction<String,String,String>> mapper)
    ロギング構成を更新します。

    クラスオブジェクトで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    修飾子と型
    メソッド
    説明
    protected Object
    clone()
    このオブジェクトのコピーを作成して、返します。
    boolean
    equals(Object obj)
    このオブジェクトと他のオブジェクトが等しいかどうかを示します。
    protected void
    finalize()
    削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
    最終決定は非推奨であり、将来のリリースで削除される可能性があります。
    final Class<?>
    getClass()
    このObjectの実行時クラスを返します。
    int
    hashCode()
    このオブジェクトに対するハッシュ・コード値を返します。
    final void
    notify()
    このオブジェクトのモニターで待機中のスレッドを1つ再開します。
    final void
    notifyAll()
    このオブジェクトのモニターで待機中のすべてのスレッドを再開します。
    String
    toString()
    オブジェクトの文字列表現を返します。
    final void
    wait()
    現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。
    final void
    wait(long timeoutMillis)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。
    final void
    wait(long timeoutMillis, int nanos)
    現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

  • フィールド詳細

  • コンストラクタの詳細

    • LogManager

      protected LogManager()
      protectedコンストラクタです。 これがprotectedになっているのは、J2EEコンテナなどのコンテナ・アプリケーションが、このオブジェクトのサブクラスを作成できるようにするためです。 これがpublicでないのは、LogManagerオブジェクトが1つしか存在しない状況が想定されているからです。その値を取得するには、Logmanager.getLogManagerを呼び出します。

  • メソッドの詳細

    • getLogManager

      public static LogManager getLogManager()
      グローバルなLogManagerオブジェクトを返します。
      戻り値:
      グローバルなLogManagerオブジェクト

    • addLogger

      public boolean addLogger(Logger logger)
      名前付きロガーを追加します。 これは、同じ名前のロガーがすでに登録されている場合、何もせずにfalseを返します。

      Loggerのファクトリ・メソッドは、このメソッドを呼び出して、新規に作成された各Loggerを登録します。

      アプリケーションは、このLoggerオブジェクトへの独自の参照を保持すべきです。それにより、このオブジェクトがガベージ・コレクトされるのを防げます。 LogManagerは弱参照しか保持できません。

      パラメータ:
      logger - 新しいロガー。
      戻り値:
      引数loggerが正常に登録された場合はtrue、その名前のロガーがすでに存在する場合はfalse
      スロー:
      NullPointerException - ロガーの名前がnullの場合。

    • getLogger

      public Logger getLogger(String name)
      名前付きロガーを検出するメソッドです。

      信頼できないコードが任意の名前のロガーを作成する場合があるので、このメソッドはセキュリティ上重要なロギング用のLoggerの検出には使用しないでください。 文字列nameに関連付けられたLoggerは、Loggerへの強い参照がない場合に、いつでもガベージ・コレクトされる可能性があることを理解することも重要です。 このメソッドの呼出し元は、Loggerがガベージ・コレクトされた場合に適切に対処するため、nullの戻り値を確認する必要があります。

      パラメータ:
      name - ロガーの名前
      戻り値:
      一致するロガー、または見つからない場合はnull

    • getLoggerNames

      public Enumeration<String> getLoggerNames()
      既知のロガーの名前の列挙を返します。

      ノート: Loggerは新しいクラスがロードされると動的に追加されます。 このメソッドは現在登録されているロガーのみについて通知します。 このメソッドは、Loggerそのものへの強い参照ではなく、Loggerの名前だけを返すことを理解しておくことも重要です。 返された文字列は、Loggerのガベージ・コレクションを防ぐことについては、何も行いません。 特に、返された名前がLogManager.getLogger()に渡された場合は、このメソッドによって名前が返された時点以降にLoggerがガベージ・コレクトされる場合に適切に対処するため、呼出し元はLogManager.getLogger()からのnullの戻り値を確認する必要があります。

      戻り値:
      ロガー名の文字列の列挙

    • readConfiguration

      public void readConfiguration() throws IOException
      ロギング構成を読み取り、初期化します。

      "java.util.logging.config.class"システム・プロパティが設定されている場合、プロパティ値はクラス名として扱われます。 指定されたクラスがロードされ、オブジェクトが1つインスタンス化されますが、そのオブジェクトのコンストラクタが初期構成を読込みを行います。 このオブジェクトは、構成を制御するためにほかのシステム・プロパティを使用する場合があります。 代替構成クラスは、readConfiguration(InputStream)を使用してLogManagerのプロパティを定義できます。

      "java.util.logging.config.class"システム・プロパティが設定されていない場合、このメソッドはプロパティ・ファイルから初期構成を読み取り、readConfiguration(InputStream)メソッドをコールして構成を初期化します。 "java.util.logging.config.file"システム・プロパティを使用して、初期構成として読み取るプロパティ・ファイルを指定できます。設定しない場合は、LogManagerデフォルト構成が使用されます。 デフォルト構成は、通常、Javaインストール・ディレクトリのプロパティ・ファイル"conf/logging.properties"からロードされます。

      「登録された構成リスナー」は、プロパティの読取り後に呼び出されます。

      APIのノート:
      このreadConfigurationメソッドは、LogManagerの初期化中、または"java.util.logging.config.class"プロパティとともに使用する場合のみ、構成の初期化に使用する必要があります。 このメソッドがロガーの作成後にコールされ、"java.util.logging.config.class"システム・プロパティが設定されていない場合、既存のすべてのロガーはresetになります。 次に、新しい構成ストリームでレベル・プロパティが指定されている既存のロガーは、指定されたログ・レベルまでsetになります。

      ロギング構成を正しく更新するには、かわりにupdateConfiguration(java.util.function.Function)またはupdateConfiguration(java.io.InputStream, java.util.function.Function)メソッドを使用します。

      スロー:
      IOException - 構成を読み込むときに入出力の問題が発生した場合。

    • reset

      public void reset()
      ログの構成をリセットします。

      すべての名前付きロガーについて、リセット操作はすべてのハンドラを削除およびクローズし、(ルート・ロガーを除いて)はレベルをnullに設定します。 ルート・ロガーのレベルは、Level.INFOに設定されます。

      APIのノート:
      このメソッドを呼び出すと、LogManager propertiesもクリアされます。 updateConfiguration(Function)またはupdateConfiguration(InputStream, Function)メソッドを使用して、新しい構成に正しく更新できます。

    • readConfiguration

      public void readConfiguration(InputStream ins) throws IOException
      指定された入力ストリームからロギング構成を読み取り、初期化します。

      「登録された構成リスナー」は、プロパティの読取り後に呼び出されます。

      APIのノート:
      このreadConfigurationメソッドは、LogManagerの初期化中、または"java.util.logging.config.class"プロパティとともに使用する場合のみ、構成の初期化に使用する必要があります。 このメソッドがロガーの作成後にコールされると、既存のすべてのロガーがresetになります。 次に、指定された入力ストリームでレベル・プロパティが指定されている既存のロガーは、指定されたログ・レベルに対してsetになります。

      ロギング構成を正しく更新するには、かわりにupdateConfiguration(java.util.function.Function)またはupdateConfiguration(java.io.InputStream, java.util.function.Function)メソッドを使用します。

      パラメータ:
      ins - プロパティを読み込むストリーム
      スロー:
      IOException - ストリームからの読取りに問題がある場合、または指定されたストリームが「プロパティ・ファイル」形式でない場合。

    • updateConfiguration

      public void updateConfiguration(Function<String, BiFunction<String,String,String>> mapper) throws IOException
      ロギング構成を更新します。

      "java.util.logging.config.file"システム・プロパティが設定されている場合、プロパティ値は、新しい構成として読み取るプロパティ・ファイルを指定します。 それ以外の場合は、LogManagerのデフォルト構成が使用されます。
      デフォルト構成は、通常、Javaインストール・ディレクトリのプロパティ・ファイル"conf/logging.properties"からロードされます。

      このメソッドは、新しい構成を読み取り、updateConfiguration(ins, mapper)メソッドをコールして構成を更新します。

      APIのノート:
      このメソッドは、ロギング構成がプロパティ・ファイルの読取りから更新され、"java.util.logging.config.class"システム・プロパティは無視されます。 "java.util.logging.config.class"プロパティは、カスタム構成クラスを初期構成としてロードするためにreadConfiguration()メソッドによってのみ使用されます。
      パラメータ:
      mapper - 構成キーkを取得し、結果の構成に返された値が適用されるファンクションf(o,n)を返すファンクション・インタフェース。 関数fは、nullを返して、プロパティkが結果の構成に追加されないことを示します。
      mapperがnullの場合、(k) -> ((o, n) -> n)とみなされます。
      各kために、マッピングされたファンクションfは古い構成(i.e o)でkと新しい構成(i.e. n)にkに関連付けられた値に関連付けられた値を用いて呼び出されます。
      oまたはnのnull値は、対応する構成でkの値が存在しないことを示します。
      スロー:
      NullPointerException - mapperが呼び出されたときにnullファンクションを返す場合。
      IOException - ロギング構成ファイルからの読取りで問題が発生した場合。
      導入されたバージョン:
      9
      関連項目:

    • updateConfiguration

      public void updateConfiguration(InputStream ins, Function<String, BiFunction<String,String,String>> mapper) throws IOException
      ロギング構成を更新します。

      「既存の構成」の構成キーおよび指定された入力ストリーム構成ごとに、指定されたmapperファンクションが呼び出され、構成キーからファンクションf(o,n)にマップされます。このファンクションは、古い値と新しい値を取得し、結果の構成で適用される結果の値を戻します(次の表を参照)。

      kを古い構成または新しい構成の構成キーにし、oを古い値(例えば、古い構成のkに関連付けられた値)にし、nを新しい値(新しい構成のkに関連する値)にし、fをmapper.apply( k )によって返される関数にします: v = f(o,n)は結果の値です。 vがnullでない場合、値vを持つプロパティkが結果の構成に追加されます。 そうしないと、省略されます。
      nullの値を関数fに渡して、対応する構成に構成キーkがないことを示すことができます。       関数fは、nullを返して、結果の構成でkに関連付けられた値がないことを示します。

      mapperがnullの場合、vはnに設定されます。

      LogManager propertiesは、結果の構成で結果の値で更新されます。

      登録された「構成リスナー」は、構成が正常に更新された後に呼び出されます。

      構成プロパティの更新
      プロパティ 結果として生じる行動
      <logger>.level
      • 結果の構成でロガーのレベルが定義され、結果のレベルが古い構成で指定されているレベルと異なるか、または指定されていないか古い構成の場合、ロガーが存在するか、そのロガーの子が存在する場合は、そのロガーのレベルが更新され、変更は既存のロガーの子に伝播されます。 これにより、必要に応じてロガーが作成される場合があります。
      • 古い構成でロガーのレベルが定義されていて、結果の構成がそうでない場合、この変更は既存のロガー(ある場合)に伝播されません。 構成を完全に置き換えるには - したがって、呼出し側は、updateConfigurationをコールする前に、resetをコールして現在の構成を空にする必要があります。
      <logger>.useParentHandlers
      • useParentHandlersプロパティの結果値または古い値のいずれかがnullでない場合、ロガーが存在するか、そのロガーの子が存在する場合、そのロガーは結果の値に更新されます。 useParentHandlersプロパティの値は、構成で指定された値です。指定しない場合、デフォルトはtrueです。
      <logger>.handlers
      • 結果の構成でロガーのハンドラのリストが定義され、結果のリストがそのロガー(それは空でもよい)の古い構成で指定されているリストと異なる場合、ロガー存在するか、その子が存在するか、そのロガーに関連付けられているハンドラが閉じられ、削除され、結果の構成ごとに新しいハンドラが作成され、そのロガーに追加され、必要に応じてそのロガーが作成されます。
      • 古い構成でロガーのハンドラが定義されていて、結果の構成でなかった場合、そのロガーが存在すると、そのハンドラは削除されて閉じられます。
      • 既存のロガー上のハンドラのリストを変更すると、構成から作成されたものかプログラム的に作成されたものかに関係なく、以前のすべてのハンドラが削除およびクローズされます。 古いハンドラは、新しいハンドラ(ある場合)に置き換えられます。
      <handler-name>.*
      • ハンドラ・クラスで構成または変更されたプロパティは、新しく作成されたハンドラにのみ影響します。 古い構成と結果の構成で同じハンドラのリストを持つノードが構成されている場合、これらのハンドラは変更されません。
      configと他のプロパティ
      • これらのプロパティの結果の値はLogManagerプロパティに格納されますが、updateConfigurationはそれらの値を解析または処理しません。

      マッパー関数の例:

      • すべてのログ・プロパティを新しい構成に置き換えます:

        (k) -> ((o, n) -> n):

        これは、nullのmapperパラメータを渡すことと同じです。
      • kが新しい構成に存在する場合は、新しい構成と古い構成をマージし、新しい値を使用します:

        (k) -> ((o, n) -> n == null ? o : n) :

        次のように2つのコレクションをマージする場合 : result.putAll(oldc); result.putAll(newc)。
      • kが古い構成に存在する場合は、新しい構成と古い構成をマージし、古い値を使用します:

        (k) -> ((o, n) -> o == null ? n : o) :

        次のように2つのコレクションをマージする場合 : result.putAll(newc); result.putAll(oldc)。
      • すべてのプロパティをハンドラ・プロパティを除く新しい構成に置き換えて、ルート・ロガーではないLoggerのハンドラを構成します: 
        (k) -> k.endsWith(".handlers")
         ? ((o, n) -> (o == null ? n : o))
         : ((o, n) -> n)

      構成を完全に再初期化するために、アプリケーションはまずresetをコールして古い構成を完全に削除し、次にupdateConfigurationをコールして新しい構成を初期化できます。

      パラメータ:
      ins - プロパティを読み込むストリーム
      mapper - 構成キーkを取得し、結果の構成に返された値が適用されるファンクションf(o,n)を返すファンクション・インタフェース。 関数fは、nullを返して、プロパティkが結果の構成に追加されないことを示します。
      mapperがnullの場合、(k) -> ((o, n) -> n)とみなされます。
      各kために、マッピングされたファンクションfは古い構成(i.e o)でkと新しい構成(i.e. n)にkに関連付けられた値に関連付けられた値を用いて呼び出されます。
      oまたはnのnull値は、対応する構成でkの値が存在しないことを示します。
      スロー:
      NullPointerException - insがnullの場合、またはmapperが呼び出されたときにnull関数を返す場合。
      IOException - ストリームからの読取りに問題がある場合、または指定されたストリームが「プロパティ・ファイル」形式でない場合。
      導入されたバージョン:
      9

    • getProperty

      public String getProperty(String name)
      ログのプロパティの値を返します。 そのプロパティが見つからない場合は、nullが返されます。
      パラメータ:
      name - プロパティ名
      戻り値:
      プロパティの値

    • checkAccess

      @Deprecated(since="17", forRemoval=true) public void checkAccess()
      削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
      このメソッドは当初、ロギング構成を変更するために現在のコンテキストが信頼できることをチェックしました。 このメソッドは、サポートされなくなった「セキュリティ・マネージャ」と組み合わせてのみ有用でした。 Security Managerまたはこのメソッドに置換はありません。
      何も行いません。

    • getLoggingMXBean

      @Deprecated(since="9") public static LoggingMXBean getLoggingMXBean()
      非推奨。
      java.util.logging.LoggingMXBeanは非推奨され、java.lang.management.PlatformLoggingMXBeanに置き換えられました。 かわりにManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class)を使用してください。
      ログ出力を管理するためのLoggingMXBeanを返します。
      戻り値:
      LoggingMXBeanオブジェクト。
      導入されたバージョン:
      1.5
      関連項目:

    • addConfigurationListener

      public LogManager addConfigurationListener(Runnable listener)
      ロギング構成が読み取られるたびに起動する構成リスナーを追加します。 リスナーがすでに登録されている場合、メソッドは何も行いません。

      リスナーは、このメソッドのコール・コンテキストによって制限される権限で起動されます。 リスナーが起動される順序は指定されていません。

      リスナーはエラーや例外をスローしないことをお薦めします。 リスナーが捕捉されないエラーまたは例外で終了した場合、すべてのリスナーが呼び出された後、最初の例外がreadConfiguration() (またはreadConfiguration(java.io.InputStream))のコール元に伝播されます。

      実装上のノート:
      複数のリスナーが捕捉されないエラーまたは例外で終了した場合、実装では追加のエラーまたは例外を「抑制された例外」として記録できます。
      パラメータ:
      listener - 構成の変更後に起動される構成リスナー。
      戻り値:
      このLogManager。
      スロー:
      NullPointerException - リスナーがnullである場合
      導入されたバージョン:
      9

    • removeConfigurationListener

      public void removeConfigurationListener(Runnable listener)
      以前に登録した構成リスナーを削除します。 リスナーが見つからない場合、サイレントを返します。
      パラメータ:
      listener - 削除する構成リスナー。
      スロー:
      NullPointerException - リスナーがnullである場合
      導入されたバージョン:
      9