Most visited

Recently visited

Added in API level 1

LogManager

public class LogManager
extends Object

java.lang.Object
   ↳ java.util.logging.LogManager


There is a single global LogManager object that is used to maintain a set of shared state about Loggers and log services.

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.

By default, the LogManager reads its initial configuration from a properties file "lib/logging.properties" in the JRE directory. If you edit that property file you can change the default logging configuration for all uses of that JRE.

In addition, the LogManager uses two optional system properties that allow more control over reading the initial configuration:

These two properties may be set via the Preferences API, or as command line property definitions to the "java" command, or as system property definitions passed to JNI_CreateJavaVM.

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, as described above, the LogManager will read its initial configuration from a properties file "lib/logging.properties" in the JRE 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:

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.

Summary

Constants

String LOGGING_MXBEAN_NAME

String representation of the ObjectName for the management interface for the logging facility.

Protected constructors

LogManager()

Protected constructor.

Public methods

boolean addLogger(Logger logger)

Add a named logger.

void addPropertyChangeListener(PropertyChangeListener l)

Adds an event listener to be invoked when the logging properties are re-read.

void checkAccess()

Check that the current context is trusted to modify the logging configuration.

static LogManager getLogManager()

Return the global LogManager object.

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.

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 removePropertyChangeListener(PropertyChangeListener l)

Removes an event listener for property change events.

void reset()

Reset the logging configuration.

Inherited methods

From class java.lang.Object

Constants

LOGGING_MXBEAN_NAME

Added in API level 1
String LOGGING_MXBEAN_NAME

String representation of the ObjectName for the management interface for the logging facility.

See also:

Constant Value: "java.util.logging:type=Logging"

Protected constructors

LogManager

Added in API level 1
LogManager ()

Protected constructor. This is protected so that container applications (such as J2EE containers) can subclass the object. It is non-public as it is intended that there only be one LogManager object, whose value is retrieved by calling Logmanager.getLogManager.

Public methods

addLogger

Added in API level 1
boolean addLogger (Logger logger)

Add a named logger. This does nothing and returns false if a logger with the same name is already registered.

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.

Parameters
logger Logger: the new logger.
Returns
boolean true if the argument logger was registered successfully, false if a logger of that name already exists.
Throws
NullPointerException if the logger name is null.

addPropertyChangeListener

Added in API level 3
void addPropertyChangeListener (PropertyChangeListener l)

Adds an event listener to be invoked when the logging properties are re-read. Adding multiple instances of the same event Listener results in multiple entries in the property event listener table.

Parameters
l PropertyChangeListener: event listener
Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").
NullPointerException if the PropertyChangeListener is null.

checkAccess

Added in API level 1
void checkAccess ()

Check that the current context is trusted to modify the logging configuration. This requires LoggingPermission("control").

If the check fails we throw a SecurityException, otherwise we return normally.

Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").

getLogManager

Added in API level 1
LogManager getLogManager ()

Return the global LogManager object.

Returns
LogManager

getLogger

Added in API level 1
Logger getLogger (String name)

Method to find a named logger.

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.

Parameters
name String: name of the logger
Returns
Logger matching logger or null if none is found

getLoggerNames

Added in API level 1
Enumeration<String> getLoggerNames ()

Get an enumeration of known logger names.

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.

Returns
Enumeration<String> enumeration of logger name strings

getLoggingMXBean

Added in API level 3
LoggingMXBean getLoggingMXBean ()

Returns LoggingMXBean for managing loggers.

Returns
LoggingMXBean a LoggingMXBean object.

getProperty

Added in API level 1
String getProperty (String name)

Get the value of a logging property. The method returns null if the property is not found.

Parameters
name String: property name
Returns
String property value

readConfiguration

Added in API level 1
void readConfiguration ()

Reinitialize the logging properties and reread the logging configuration.

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.

A PropertyChangeEvent will be fired after the properties are read.

Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").
IOException if there are IO problems reading the configuration.

readConfiguration

Added in API level 1
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. A PropertyChangeEvent will be fired after the properties are read.

Any log level definitions in the new configuration file will be applied using Logger.setLevel(), if the target Logger exists.

Parameters
ins InputStream: stream to read properties from
Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").
IOException if there are problems reading from the stream.

removePropertyChangeListener

Added in API level 3
void removePropertyChangeListener (PropertyChangeListener l)

Removes an event listener for property change events. If the same listener instance has been added to the listener table through multiple invocations of addPropertyChangeListener, then an equivalent number of removePropertyChangeListener invocations are required to remove all instances of that listener from the listener table.

Returns silently if the given listener is not found.

Parameters
l PropertyChangeListener: event listener (can be null)
Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").

reset

Added in API level 1
void reset ()

Reset the logging configuration.

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.

Throws
SecurityException if a security manager exists and if the caller does not have LoggingPermission("control").

Hooray!