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.
The LogManager defines two optional system properties that allow control over the initial configuration:
If the "java.util.logging.config.class" 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" property is not set, then the "java.util.logging.config.file" system property can be used to specify a properties file (in java.util.Properties format). The initial logging configuration will be read from this file.
If neither of these properties is defined then the LogManager uses its
default configuration. The default configuration is typically loaded from the
properties file "conf/logging.properties
" in the Java installation
directory.
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 and Description |
---|---|
static String |
LOGGING_MXBEAN_NAME
String representation of the
ObjectName for the management interface
for the logging facility. |
Modifier | Constructor and Description |
---|---|
protected |
LogManager()
Protected constructor.
|
Modifier and Type | Method and Description |
---|---|
LogManager |
addConfigurationListener(Runnable listener)
Adds a configuration listener to be invoked each time the logging
configuration is read.
|
boolean |
addLogger(Logger logger)
Add a named logger.
|
void |
checkAccess()
Check that the current context is trusted to modify the logging
configuration.
|
Logger |
getLogger(String name)
Method to find a named logger.
|
Enumeration<String> |
getLoggerNames()
Get an enumeration of known logger names.
|
static LoggingMXBean |
getLoggingMXBean()
Returns
LoggingMXBean for managing loggers. |
static LogManager |
getLogManager()
Returns the global LogManager object.
|
String |
getProperty(String name)
Get the value of a logging property.
|
void |
readConfiguration()
Reinitialize the logging properties and reread the logging configuration.
|
void |
readConfiguration(InputStream ins)
Reinitialize the logging properties and reread the logging configuration
from the given stream, which should be in java.util.Properties format.
|
void |
removeConfigurationListener(Runnable listener)
Removes a previously registered configuration listener.
|
void |
reset()
Reset the logging configuration.
|
public static final String LOGGING_MXBEAN_NAME
ObjectName
for the management interface
for the logging facility.PlatformLoggingMXBean
,
LoggingMXBean
,
Constant Field Valuesprotected 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
The same rules are used for locating the configuration properties as are used at startup. So normally the logging properties will be re-read from the same file that was used at startup.
Any log level definitions in the new configuration file will be applied using Logger.setLevel(), if the target Logger exists.
Any registered configuration listener will be invoked after the properties are read.
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.
SecurityException
- if a security manager exists and if
the caller does not have LoggingPermission("control").public void readConfiguration(InputStream ins) throws IOException, SecurityException
Any log level definitions in the new configuration file will be applied using Logger.setLevel(), if the target Logger exists.
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.public String getProperty(String name)
name
- property namepublic 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").public static LoggingMXBean getLoggingMXBean()
LoggingMXBean
for managing loggers.
An alternative way to manage loggers is through the
PlatformLoggingMXBean
interface
that can be obtained by calling:
PlatformLoggingMXBean logging = ManagementFactory.getPlatformMXBean
(PlatformLoggingMXBean.class);
LoggingMXBean
object.PlatformLoggingMXBean
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"). Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.
DRAFT internal-b80