この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
-
フィールドのサマリー
フィールド -
コンストラクタのサマリー
コンストラクタ -
メソッドのサマリー
修飾子と型メソッド説明addConfigurationListener
(Runnable listener) ロギング構成が読み取られるたびに起動する構成リスナーを追加します。boolean
名前付きロガーを追加します。void
非推奨、削除予定: このAPI要素は将来のバージョンで削除予定です。このメソッドは、非推奨であり、今後のリリースで削除される可能性があります。「セキュリティ・マネージャ」と組み合わせて使用すると便利です。名前付きロガーを検出するメソッドです。既知のロガーの名前の列挙を返します。static LoggingMXBean
非推奨。java.util.logging.LoggingMXBean
は非推奨され、java.lang.management.PlatformLoggingMXBean
に置き換えられました。static LogManager
グローバルなLogManagerオブジェクトを返します。getProperty
(String name) ログのプロパティの値を返します。void
ロギング構成を読み取り、初期化します。void
指定された入力ストリームからロギング構成を読み取り、初期化します。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) ロギング構成を更新します。
-
フィールド詳細
-
LOGGING_MXBEAN_NAME
public static final String LOGGING_MXBEAN_NAMEロギング機能の管理インタフェースのObjectName
の文字列表現。- 導入されたバージョン:
- 1.5
- 関連項目:
-
-
コンストラクタの詳細
-
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
名前付きロガーを検出するメソッドです。信頼できないコードが任意の名前のロガーを作成する場合があるので、このメソッドはセキュリティ上重要なロギング用の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, throws IOExceptionString, String>> mapper) ロギング構成を更新します。"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
public void updateConfiguration(InputStream ins, Function<String, BiFunction<String, throws IOExceptionString, String>> mapper) ロギング構成を更新します。「既存の構成」の構成キーおよび指定された入力ストリーム構成ごとに、指定された
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の値が存在しないことを示します。- 例外:
SecurityException
- セキュリティ・マネージャが存在し、コール元にLoggingPermission("control")がない場合、または構成(FileHandlersに指定されたオープン・ファイル)の設定に必要な権限がない場合NullPointerException
-ins
がnullの場合、またはmapper
が呼び出されたときにnull関数を返す場合。IOException
- ストリームからの読取りに問題がある場合、または指定されたストリームが「プロパティ・ファイル」形式でない場合。- 導入されたバージョン:
- 9
-
getProperty
ログのプロパティの値を返します。 そのプロパティが見つからない場合は、nullが返されます。- パラメータ:
name
- プロパティ名- 戻り値:
- プロパティの値
-
checkAccess
@Deprecated(since="17", forRemoval=true) public void checkAccess() throws SecurityException非推奨、削除予定: このAPI要素は将来のバージョンで削除予定です。このメソッドは、非推奨であり、今後のリリースで削除される可能性があります。「セキュリティ・マネージャ」と組み合わせて使用すると便利です。 そのため、このメソッドは非推奨であり、削除される可能性があります。 Security Managerまたはこのメソッドに置換はありません。現在のコンテキストが信頼されていてロギング構成を変更できるかどうかをチェックします。 これには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
- 関連項目:
-
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
-