モジュール 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に渡されるシステム・プロパティ定義として指定することもできます。

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

    • 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」システム・プロパティが設定されていない場合、既存のすべてのロガーはリセットされます。 その後、新しい構成ストリームでレベル・プロパティが指定されている既存のロガーは、指定されたログ・レベルに設定されます。

        ロギング構成を正しく更新するには、かわりに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プロパティもクリアされます。 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プロパティとともに使用する場合にかぎり、構成の初期化に使用する必要があります。 このメソッドがロガーの作成後に呼び出されると、既存のすべてのロガーがリセットされます。 この場合、指定された入力ストリームでレベルプロパティーが指定されている既存のロガーは、指定されたログレベルに 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が、古い構成(つまり o)の kに関連付けられた値、および新しい構成(つまり 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を古い構成または新しい構成の構成キーとし、oを古い値(つまり、古い構成でkに関連付けられている値)、nを新しい値(つまり、新しい構成でkに関連付けられている値)とし、fをmapper.apply(k)によって返される関数にします。次に、v = f(o、n)が結果の値になります。 vが nullでない場合、値 vのプロパティー kが結果の構成に追加されます。 それ以外の場合は、省略されます。
        null値を関数fに渡して、対応する構成に構成キーkがないことを示すことができます。         関数 fは、結果の構成で kに関連付けられた値がないことを示す nullを返すことがあります。

        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が、古い構成(つまり o)の kに関連付けられた値、および新しい構成(つまり 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))のコール元に伝播されます。

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

      • removeConfigurationListener

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