モジュール java.logging
パッケージ 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

    • コンストラクタの詳細

      • 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,
                              SecurityException
        ロギング構成を読み込み、初期化します。

        "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)メソッドを使用してください。

        例外:
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
        IOException - 構成を読み込むときに入出力の問題が発生した場合。

      • reset

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

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

        APIに関するノート:
        このメソッドを呼び出すと、LogManager propertiesもクリアされます。 updateConfiguration(Function)またはupdateConfiguration(InputStream, Function)メソッドを使用して、新しい構成に正しく更新できます。
        例外:
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。

      • readConfiguration

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

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

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

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

        パラメータ:
        ins - プロパティを読み込むストリーム
        例外:
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
        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に値が存在しないことを示します。
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にLoggingPermission("control")がない場合、または構成を設定するために必要な許可がない場合(FileHandlersなどで指定されたファイルを開く...)
        NullPointerException - mapperが呼び出されたときにnull関数を返す場合。
        IOException - ロギング構成ファイルからの読み込みに問題がある場合。
        導入されたバージョン:
        9
        関連項目:
        updateConfiguration(java.io.InputStream, java.util.function.Function)

      • updateConfiguration

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

        「既存の構成」と指定された入力ストリームの構成の各構成をキーに、所与mapper関数は古い値と新しい値を取り、に適用されるべき結果の値を返す関数、f(o,n)、に設定キーからマッピングするために呼び出されます結果の構成は、以下の表で指定されています。

        新しい値(新しい構成のkに関連する値)ことn、およびmapper.apply( k )によって返された関数であるf、古い値(例えば、古い構成のkに関連付けられた値)ことo、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)。
        • すべてのプロパティを、ハンドラ・プロパティ以外の新しい構成で置き換えて、root 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に値が存在しないことを示します。
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にLoggingPermission("control")がない場合、または構成を設定するために必要な許可がない場合(FileHandlersに指定されたオープン・ファイル)
        NullPointerException - insがnullの場合、またはmapperが呼び出されたときにnull関数を返す場合。
        IOException - ストリームからの読み込みに問題がある場合、または指定されたストリームが「プロパティ・ファイル」形式でない場合。
        導入されたバージョン:
        9

      • getProperty

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

      • checkAccess

        public void checkAccess()
                 throws SecurityException
        現在のコンテキストが信頼されていてロギング構成を変更できるかどうかをチェックします。 これにはLoggingPermission("control")が必要となります。

        このチェックに失敗した場合はSecurityExceptionをスローします。そうでない場合は正常に復帰します。

        例外:
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。

      • getLoggingMXBean

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

      • addConfigurationListener

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

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

        リスナーがエラーや例外をスローしないようにすることをお勧めします。 リスナーがキャッチされていないエラーまたは例外で終了すると、最初の例外はすべてのリスナーが呼び出された後にreadConfiguration() (またはreadConfiguration(java.io.InputStream))の呼び出し元に伝播されます。

        実装上のノート:
        1つ以上のリスナーがキャッチされないエラーまたは例外で終了する場合、実装は追加のエラーまたは例外を「抑制された例外」として記録することがあります。
        パラメータ:
        listener - 構成が変更された後に呼び出される構成リスナー。
        戻り値:
        このLogManager。
        例外:
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
        NullPointerException - リスナーがnullである場合
        導入されたバージョン:
        9

      • removeConfigurationListener

        public void removeConfigurationListener​(Runnable listener)
        以前に登録された構成リスナーを削除します。 リスナーが見つからない場合は、自動的に戻ります。
        パラメータ:
        listener - 削除する構成リスナー。
        例外:
        NullPointerException - リスナーがnullである場合
        SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
        導入されたバージョン:
        9