java.util.logging
Class LogManager

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

public class LogManager
extends Object

LogManager is used to maintain configuration properties of the logging framework, and to manage a hierarchical namespace of all named Logger objects.

There is only one global LogManager instance in the application, which can be get by calling static method LogManager.getLogManager(). This instance is created and initialized during class initialization and cannot be changed.

The LogManager class can be specified by java.util.logging.manager system property, if the property is unavailable or invalid, the default class java.util.logging.LogManager will be used.

When initialization, LogManager read its configuration from a properties file, which by default is the "lib/logging.properties" in the JRE directory.

However, two optional system properties can be used to customize the initial configuration process of LogManager.

• "java.util.logging.config.class"
• "java.util.logging.config.file"

These two properties can be set in three ways, by the Preferences API, by the "java" command line property definitions, or by system property definitions passed to JNI_CreateJavaVM.

The "java.util.logging.config.class" should specifies a class name. If it is set, this given class will be loaded and instantiated during LogManager initialization, so that this object's default constructor can read the initial configuration and define properties for LogManager.

If "java.util.logging.config.class" property is not set, or it is invalid, or some exception is thrown during the instantiation, then the "java.util.logging.config.file" system property can be used to specify a properties file. The LogManager will read initial configuration from this file.

If neither of these properties is defined, or some exception is thrown during these two properties using, the LogManager will read its initial configuration from default properties file, as described above.

The global logging properties may include:

• "handlers". This property's values should be a list of class names for handler classes separated by whitespace, these classes must be subclasses of Handler and each must have a default constructor, these classes will be loaded, instantiated and registered as handlers on the root Logger (the Logger named ""). These Handlers maybe initialized lazily.
• "config". The property defines a list of class names separated by whitespace. Each class must have a default constructor, in which it can update the logging configuration, such as levels, handlers, or filters for some logger, etc. These classes will be loaded and instantiated during LogManager configuration

This class, together with any handler and configuration classes associated with it, must be loaded from the system classpath when LogManager configuration occurs.

Besides global properties, the properties for loggers and Handlers can be specified in the property files. The names of these properties will start with the complete dot separated names for the handlers or loggers.

In the LogManager's hierarchical namespace, Loggers are organized based on their dot separated names. For example, "x.y.z" is child of "x.y".

Levels for Loggers can be defined by properties whose name end with ".level". Thus "alogger.level" defines a level for the logger named as "alogger" and for all its children in the naming hierarchy. Log levels properties are read and applied in the same order as they are specified in the property file. The root logger's level can be defined by the property named as ".level".

All methods on this type can be taken as being thread safe.

Field Summary

static String	LOGGING_MXBEAN_NAME The String value of the LoggingMXBean's ObjectName.
(package private) static LogManager	manager

Constructor Summary

protected

LogManager() Default constructor.

Method Summary

boolean	addLogger(Logger logger) Add a given logger into the hierarchical namespace.
void	checkAccess() Check that the caller has LoggingPermission("control") so that it is trusted to modify the configuration for logging framework.
(package private) static Object	getInstanceByClass(String className)
Logger	getLogger(String name) Get the logger with the given name
Enumeration<String>	getLoggerNames() Get a Enumeration of all registered logger names
static LogManager	getLogManager() Get the global LogManager instance
(package private) static String	getPrivilegedSystemProperty(String key)
String	getProperty(String name) Get the value of property with given name
(package private) static String	getSystemLineSeparator()
void	readConfiguration() Re-initialize the properties and configuration.
void	readConfiguration(InputStream ins) Re-initialize the properties and configuration from the given InputStream
void	reset() Reset configuration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

manager

static LogManager manager

LOGGING_MXBEAN_NAME

public static final String LOGGING_MXBEAN_NAME

The String value of the LoggingMXBean's ObjectName.

See Also:

Constant Field Values

Constructor Detail

LogManager

protected LogManager()

Default constructor. This is not public because there should be only one LogManager instance, which can be get by LogManager.getLogManager(. This is protected so that application can subclass the object.

Method Detail

getSystemLineSeparator

static String getSystemLineSeparator()

checkAccess

public void checkAccess()

Check that the caller has LoggingPermission("control") so that it is trusted to modify the configuration for logging framework. If the check passes, just return, otherwise SecurityException will be thrown.

Throws:

SecurityException - if there is a security manager in operation and the invoker of this method does not have the required security permission LoggingPermission("control")

addLogger

public boolean addLogger(Logger logger)

Add a given logger into the hierarchical namespace. The Logger.addLogger() factory methods call this method to add newly created Logger. This returns false if a logger with the given name has existed in the namespace

Note that the LogManager may only retain weak references to registered loggers. In order to prevent Logger objects from being unexpectedly garbage collected it is necessary for applications to maintain references to them.

Parameters:

logger - the logger to be added

Returns:

true if the given logger is added into the namespace successfully, false if the logger of given name has existed in the namespace

getLogger

public Logger getLogger(String name)

Get the logger with the given name

Parameters:

name - name of logger

Returns:

logger with given name, or null if nothing is found

getLoggerNames

public Enumeration<String> getLoggerNames()

Get a Enumeration of all registered logger names

Returns:

enumeration of registered logger names

getLogManager

public static LogManager getLogManager()

Get the global LogManager instance

Returns:

the global LogManager instance

getProperty

public String getProperty(String name)

Get the value of property with given name

Parameters:

name - the name of property

Returns:

the value of property

readConfiguration

public void readConfiguration()
                       throws IOException

Re-initialize the properties and configuration. The initialization process is same as the LogManager instantiation.

A PropertyChangeEvent must be fired.

Throws:

IOException - if any IO related problems happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to perform this action

getPrivilegedSystemProperty

static String getPrivilegedSystemProperty(String key)

getInstanceByClass

static Object getInstanceByClass(String className)

readConfiguration

public void readConfiguration(InputStream ins)
                       throws IOException

Re-initialize the properties and configuration from the given InputStream

A PropertyChangeEvent must be fired.

Parameters:

ins - the input stream.

Throws:

IOException - if any IO related problems happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to perform this action

reset

public void reset()

Reset configuration.

All handlers are closed and removed from any named loggers. All loggers' level is set to null, except the root logger's level is set to Level.INFO.

Throws:

SecurityException - if security manager exists and it determines that caller does not have the required permissions to perform this action