LogManager
As its name implies, this class is the manager for the java.util.logging API. It has three specific purposes: (1) to read a logging configuration file and create the default Handler objects specified in that file; (2) to manage a set of Logger objects, arranging them into a tree based on their heirarchical names ; and (3) to create and manage the unnamed Logger object that serves as the parent or ancestor of every other Logger . This class handles the important behind-the-scenes details that makes the Logging API work. Typical applications can make use of logging without ever having to use this class explicitly. Although its API is not commonly used by application programmers, it is still useful to understand the LogManager class, so it is described in detail here. There is a single global instance of LogManager , which is obtained with the static getLogManager( ) method. By default, this global log manager object is an instance of the LogManager class itself. You may instead instantiate an instance of a subclass of LogManager by specifing the full class name of the subclass as the value of the system property java.util.logging.manager . One of the primary purposes of the LogManager class is to read a java.util.Properties file that specifies the default logging configuration for the system. By default, this file is named logging.properties and is stored in the jre/lib directory of the Java installation. If you want to run a Java application using a different logging configuration, you can edit the default configuration file, but it is typically easier to create a new configuation file and tell the JVM about it by setting the system property java.util.logging.config.file to the name of your customized configuration file. The most important purpose of the configuration file is to specify a set of Handler objects to which all log messages are sent. This is done by setting the handlers property in the file to a space-separated list of Handler class names. The LogManager will load the specified classes, and instantiate each one (using the default no-arg constructor), and then register those Handler objects on the root Logger , where they are inherited by all other loggers. (We'll see more about the root logger below.) Each of these Handler objects further configures itself by reading additional properties from the configuration file, as described in the documentation for each handler class. The configuration file may also contain property name that are formed by appending ".level" to the name of a logger. The value of any such property is taken as the name of a logging Level for the named Logger . When the named logger is created and registered with the LogManager (described below) its logging level is automatically set to the specified level. An application or any custom Handler or Formatter subclass or Filter implementation can read its own properties from the logging configuration file with the getProperty( ) method of LogManager . This is a useful way to provide customizability for logging- related classes. In addition to managing the configuration file properties, a second purpose of LogManager is to maintain a tree of Logger objects organized into a hierarchy based on their dot-separated hierarchical names. The addLogger( ) method registers a new Logger object with the LogManager and inserts it into the tree. This method is called automatically by the Logger.getLogger( ) factory method, however, so you never need to call it yourself. The getLogger( ) method of LogManager finds and returns a named Logger object within the tree. Use getLoggerNames( ) to obtain an Enumeration of the names of all registered loggers. At the root of the tree is a root logger, created by the LogManager , and initialized with default Handler objects specified in the logging configuration file as described above. This root logger has no name, and you can obtain a reference to it by passing the empty string to the getLogger( ) method. Except for this root logger and anonymous loggers (see Logger.getAnonymousLogger( ) ), all loggers have names, and they are typically named after the package or class for which they provide logging. When a named logger is registered with the LogManager , the LogManager examines its name and inserts it into the tree of loggers at the appropriate place: a logger named "java.util.logging" would be inserted as the child of a logger named "java.util", if any such logger existed, or as a child of a logger named "java", or, if no logger with that name existed either, it would be inserted as a child of the root logger named "". When the LogManager determines the position of a logger within the tree of loggers, it calls the setParent( ) method of the newly-registered Logger to tell it who its parent is. This is important because, by default, loggers inherit their logging level and handlers from their parent. Although the Logger.setParent( ) method is public, it is intended for use only by the LogManager class. Anonymous loggers created with Logger.getAnonymousLogger( ) do not have names, and are not part of the logger tree. When they are created, however, their parent is set to the root logger of the LogManager. For this reason, anonymous loggers inherit the default handlers specified in the logging configuration file. The readConfiguration( ) methods are used to force the LogManager to re-read the system configuration file, or to read a new configuration file from the specified stream. Both versions of the method generate a java.beans.PropertyChangeEvent and use it to notify any listeners that have been registered with addPropertyChangeListener . Both methods also first invoke the reset( ) method which discards the properties of the current configuration file, removes and closes all handlers for all loggers, and sets the logging level of all loggers to null , except for the root logger's logging level, which it sets to Level.INFO . It is unlikely that you would ever want to invoke reset( ) yourself. A number of LogManager methods throw a SecurityException if the caller does not have appropriate permissions. You can use checkAccess( ) to test whether the current calling context has the required LoggingPermission named "control". All LogManager methods can be safely used by multiple threads. public class LogManager { // Protected Constructors protected LogManager ( ); // Public Constants 5.0 public static final String LOGGING_MXBEAN_NAME ; = "java.util.logging:type=Logging" // Public Class Methods 5.0 public static LoggingMXBean getLoggingMXBean ( ); synchronized public static LogManager getLogManager ( ); // Event Registration Methods (by event name) public void addPropertyChangeListener (java.beans.PropertyChangeListener l ) throws SecurityException; public void removePropertyChangeListener (java.beans.PropertyChangeListener l ) throws SecurityException; // Public Instance Methods public boolean addLogger (Logger logger ); synchronized public void checkAccess ( ) throws SecurityException; public Logger getLogger (String name ); synchronized public java.util.Enumeration<String> getLoggerNames ( ); synchronized public String getProperty (String name ); public void readConfiguration ( ) throws java.io.IOException, SecurityException; public void readConfiguration (java.io.InputStream ins ) throws java.io.IOException, SecurityException; public void reset ( ) throws SecurityException; } |
EAN: 2147483647
Pages: 1220