public class LogManager extends Object
This LogManager object:
The global LogManager object can be retrieved using LogManager.getLogManager(). The LogManager object is created during class initialization and cannot subsequently be changed.
At startup the LogManager class is located using the java.util.logging.manager system property.
readConfiguration()
method during LogManager initialization. By default, LogManager default configuration is used. The logging configuration read by LogManager must be in the properties file format. The LogManager defines two optional system properties that allow control over the initial configuration, as specified in the readConfiguration()
method:
java.util.logging.config.class
java.util.logging.config.file
These two system properties may be specified on the command line to the "java" command, or as system property definitions passed to JNI_CreateJavaVM.
The properties for loggers and Handlers will have names starting with the dot-separated name for the handler or logger.
The global logging properties may include:
true
. When the value is true
, the handlers associated with the logger are guaranteed to be closed on reset() and shutdown. This can be turned off by explicitly setting "<logger>.handlers.ensureCloseOnReset=false" in the configuration. Note that turning this property off causes the risk of introducing a resource leak, as the logger may get garbage collected before reset()
is called, thus preventing its handlers from being closed on reset()
. In that case it is the responsibility of the application to ensure that the handlers are closed before the logger is garbage collected. Note that all classes loaded during LogManager configuration are first searched on the system class path before any user class path. That includes the LogManager class, any config classes, and any handler classes.
Loggers are organized into a naming hierarchy based on their dot separated names. Thus "a.b.c" is a child of "a.b", but "a.b1" and a.b2" are peers.
All properties whose names end with ".level" are assumed to define log levels for Loggers. Thus "foo.level" defines a log level for the logger called "foo" and (recursively) for any of its children in the naming hierarchy. Log Levels are applied in the order they are defined in the properties file. Thus level settings for child nodes in the tree should come after settings for their parents. The property name ".level" can be used to set the level for the root of the tree.
All methods on the LogManager object are multi-thread safe.
Modifier and Type | Field | Description |
---|---|---|
static final String |
LOGGING_MXBEAN_NAME |
String representation of the ObjectName for the management interface for the logging facility. |
Modifier | Constructor | Description |
---|---|---|
protected |
Protected constructor. |
Modifier and Type | Method | Description |
---|---|---|
LogManager |
addConfigurationListener |
Adds a configuration listener to be invoked each time the logging configuration is read. |
boolean |
addLogger |
Add a named logger. |
void |
checkAccess() |
Deprecated, for removal: This API element is subject to removal in a future version. This method is only useful in conjunction with the Security Manager, which is deprecated and subject to removal in a future release. |
Logger |
getLogger |
Method to find a named logger. |
Enumeration |
getLoggerNames() |
Get an enumeration of known logger names. |
static LoggingMXBean |
getLoggingMXBean() |
Deprecated. java.util.logging.LoggingMXBean is deprecated and replaced with java.lang.management.PlatformLoggingMXBean . |
static LogManager |
getLogManager() |
Returns the global LogManager object. |
String |
getProperty |
Get the value of a logging property. |
void |
readConfiguration() |
Reads and initializes the logging configuration. |
void |
readConfiguration |
Reads and initializes the logging configuration from the given input stream. |
void |
removeConfigurationListener |
Removes a previously registered configuration listener. |
void |
reset() |
Reset the logging configuration. |
void |
updateConfiguration |
Updates the logging configuration. |
void |
updateConfiguration |
Updates the logging configuration. |
public static final String LOGGING_MXBEAN_NAME
ObjectName
for the management interface for the logging facility.protected LogManager()
public static LogManager getLogManager()
public boolean addLogger(Logger logger)
The Logger factory methods call this method to register each newly created Logger.
The application should retain its own reference to the Logger object to avoid it being garbage collected. The LogManager may only retain a weak reference.
logger
- the new logger.NullPointerException
- if the logger name is null.public Logger getLogger(String name)
Note that since untrusted code may create loggers with arbitrary names this method should not be relied on to find Loggers for security sensitive logging. It is also important to note that the Logger associated with the String name
may be garbage collected at any time if there is no strong reference to the Logger. The caller of this method must check the return value for null in order to properly handle the case where the Logger has been garbage collected.
name
- name of the loggerpublic Enumeration<String> getLoggerNames()
Note: Loggers may be added dynamically as new classes are loaded. This method only reports on the loggers that are currently registered. It is also important to note that this method only returns the name of a Logger, not a strong reference to the Logger itself. The returned String does nothing to prevent the Logger from being garbage collected. In particular, if the returned name is passed to LogManager.getLogger()
, then the caller must check the return value from LogManager.getLogger()
for null to properly handle the case where the Logger has been garbage collected in the time since its name was returned by this method.
public void readConfiguration() throws IOException, SecurityException
If the "java.util.logging.config.class" system property is set, then the property value is treated as a class name. The given class will be loaded, an object will be instantiated, and that object's constructor is responsible for reading in the initial configuration. (That object may use other system properties to control its configuration.) The alternate configuration class can use readConfiguration(InputStream)
to define properties in the LogManager.
If "java.util.logging.config.class" system property is not set, then this method will read the initial configuration from a properties file and calls the readConfiguration(InputStream)
method to initialize the configuration. The "java.util.logging.config.file" system property can be used to specify the properties file that will be read as the initial configuration; if not set, then the LogManager default configuration is used. The default configuration is typically loaded from the properties file "conf/logging.properties
" in the Java installation directory.
Any registered configuration listener will be invoked after the properties are read.
readConfiguration
method should only be used for initializing the configuration during LogManager initialization or used with the "java.util.logging.config.class" property. When this method is called after loggers have been created, and the "java.util.logging.config.class" system property is not set, all existing loggers will be reset. Then any existing loggers that have a level property specified in the new configuration stream will be set to the specified log level. To properly update the logging configuration, use the updateConfiguration(java.util.function.Function)
or updateConfiguration(java.io.InputStream, java.util.function.Function)
methods instead.
SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").IOException
- if there are IO problems reading the configuration.public void reset() throws SecurityException
For all named loggers, the reset operation removes and closes all Handlers and (except for the root logger) sets the level to null
. The root logger's level is set to Level.INFO
.
updateConfiguration(Function)
or updateConfiguration(InputStream, Function)
method can be used to properly update to a new configuration.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").public void readConfiguration(InputStream ins) throws IOException, SecurityException
Any registered configuration listener will be invoked after the properties are read.
readConfiguration
method should only be used for initializing the configuration during LogManager initialization or used with the "java.util.logging.config.class" property. When this method is called after loggers have been created, all existing loggers will be reset. Then any existing loggers that have a level property specified in the given input stream will be set to the specified log level. To properly update the logging configuration, use the updateConfiguration(java.util.function.Function)
or updateConfiguration(java.io.InputStream, java.util.function.Function)
method instead.
ins
- stream to read properties fromSecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").IOException
- if there are problems reading from the stream, or the given stream is not in the properties file format.public void updateConfiguration(Function<String,BiFunction<String,String,String>> mapper) throws IOException
If the "java.util.logging.config.file" system property is set, then the property value specifies the properties file to be read as the new configuration. Otherwise, the LogManager default configuration is used.
The default configuration is typically loaded from the properties file "conf/logging.properties
" in the Java installation directory.
This method reads the new configuration and calls the updateConfiguration(ins, mapper)
method to update the configuration.
readConfiguration()
method to load a custom configuration class as an initial configuration.mapper
- a functional interface that takes a configuration key k and returns a function f(o,n) whose returned value will be applied to the resulting configuration. The function f may return null
to indicate that the property k will not be added to the resulting configuration. mapper
is null
then (k) -> ((o, n) -> n)
is assumed. null
value for o or n indicates that no value was present for k in the corresponding configuration.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control"), or does not have the permissions required to set up the configuration (e.g. open file specified for FileHandlers etc...)NullPointerException
- if mapper
returns a null
function when invoked.IOException
- if there are problems reading from the logging configuration file.public void updateConfiguration(InputStream ins, Function<String,BiFunction<String,String,String>> mapper) throws IOException
For each configuration key in the existing configuration and the given input stream configuration, the given mapper
function is invoked to map from the configuration key to a function, f(o,n), that takes the old value and new value and returns the resulting value to be applied in the resulting configuration, as specified in the table below.
Let k be a configuration key in the old or new configuration, o be the old value (i.e. the value associated with k in the old configuration), n be the new value (i.e. the value associated with k in the new configuration), and f be the function returned by mapper.apply(
k)
: then v = f(o,n) is the resulting value. If v is not null
, then a property k with value v will be added to the resulting configuration. Otherwise, it will be omitted.
A null
value may be passed to function f to indicate that the corresponding configuration has no configuration key k. The function f may return null
to indicate that there will be no value associated with k in the resulting configuration.
If mapper
is null
, then v will be set to n.
LogManager properties are updated with the resulting value in the resulting configuration.
The registered configuration listeners will be invoked after the configuration is successfully updated.
Property | Resulting Behavior |
---|---|
<logger>.level |
|
<logger>.useParentHandlers |
|
<logger>.handlers |
|
<handler-name>.* |
|
config and any other property |
|
Example mapper functions:
(k) -> ((o, n) -> n)
: mapper
parameter. (k) -> ((o, n) -> n == null ? o : n)
: result.putAll(oldc); result.putAll(newc)
. (k) -> ((o, n) -> o == null ? n : o)
: result.putAll(newc); result.putAll(oldc)
.(k) -> k.endsWith(".handlers")
? ((o, n) -> (o == null ? n : o))
: ((o, n) -> n)
To completely reinitialize a configuration, an application can first call reset
to fully remove the old configuration, followed by updateConfiguration
to initialize the new configuration.
ins
- a stream to read properties frommapper
- a functional interface that takes a configuration key k and returns a function f(o,n) whose returned value will be applied to the resulting configuration. The function f may return null
to indicate that the property k will not be added to the resulting configuration. mapper
is null
then (k) -> ((o, n) -> n)
is assumed. null
value for o or n indicates that no value was present for k in the corresponding configuration.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control"), or does not have the permissions required to set up the configuration (e.g. open files specified for FileHandlers)NullPointerException
- if ins
is null or if mapper
returns a null function when invoked.IOException
- if there are problems reading from the stream, or the given stream is not in the properties file format.public String getProperty(String name)
name
- property name@Deprecated(since="17", forRemoval=true) public void checkAccess() throws SecurityException
If the check fails we throw a SecurityException, otherwise we return normally.
SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").@Deprecated(since="9") public static LoggingMXBean getLoggingMXBean()
java.util.logging.LoggingMXBean
is deprecated and replaced with java.lang.management.PlatformLoggingMXBean
. Use ManagementFactory.getPlatformMXBean
(PlatformLoggingMXBean.class) instead.LoggingMXBean
for managing loggers.LoggingMXBean
object.public LogManager addConfigurationListener(Runnable listener)
The listener is invoked with privileges that are restricted by the calling context of this method. The order in which the listeners are invoked is unspecified.
It is recommended that listeners do not throw errors or exceptions. If a listener terminates with an uncaught error or exception then the first exception will be propagated to the caller of readConfiguration()
(or readConfiguration(java.io.InputStream)
) after all listeners have been invoked.
listener
- A configuration listener that will be invoked after the configuration changed.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").NullPointerException
- if the listener is null.public void removeConfigurationListener(Runnable listener)
listener
- the configuration listener to remove.NullPointerException
- if the listener is null.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control").
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.logging/java/util/logging/LogManager.html