fixed some formatting typos

[vimdoclet.git] / sample / java.util.logging.LogManager.txt

*java.util.logging.LogManager* *LogManager* There is a single global LogManager 

public class LogManager
  extends    |java.lang.Object|

|java.util.logging.LogManager_Description|
|java.util.logging.LogManager_Fields|
|java.util.logging.LogManager_Constructors|
|java.util.logging.LogManager_Methods|

================================================================================

*java.util.logging.LogManager_Fields*
|java.lang.String_java.util.logging.LogManager.LOGGING_MXBEAN_NAME|

*java.util.logging.LogManager_Constructors*
|java.util.logging.LogManager()|Protected constructor.

*java.util.logging.LogManager_Methods*
|java.util.logging.LogManager.addLogger(Logger)|Add a named logger.
|java.util.logging.LogManager.addPropertyChangeListener(PropertyChangeListener)|
|java.util.logging.LogManager.checkAccess()|Check that the current context is t
|java.util.logging.LogManager.getLogger(String)|Method to find a named logger.
|java.util.logging.LogManager.getLoggerNames()|Get an enumeration of known logg
|java.util.logging.LogManager.getLoggingMXBean()|Returns LoggingMXBean for mana
|java.util.logging.LogManager.getLogManager()|Return the global LogManager obje
|java.util.logging.LogManager.getProperty(String)|Get the value of a logging pr
|java.util.logging.LogManager.readConfiguration()|Reinitialize the logging prop
|java.util.logging.LogManager.readConfiguration(InputStream)|Reinitialize the l
|java.util.logging.LogManager.removePropertyChangeListener(PropertyChangeListener)|
|java.util.logging.LogManager.reset()|Reset the logging configuration.

*java.util.logging.LogManager_Description*

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: 

Manages a hierarchical namespace of Logger objects. All named Loggers are 
stored in this namespace. Manages a set of logging control properties. These 
are simple key-value pairs that can be used by Handlers and other logging 
objects to configure themselves. 

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: 

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

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: 

A property "handlers". This defines a whitespace or comma separated list of 
class names for handler classes to load and register as handlers on the root 
Logger (the Logger named ""). Each class name must be for a Handler class which 
has a default constructor. Note that these Handlers may be created lazily, when 
they are first used. 

A property "<logger>.handlers". This defines a whitespace or comma separated 
list of class names for handlers classes to load and register as handlers to 
the specified logger. Each class name must be for a Handler class which has a 
default constructor. Note that these Handlers may be created lazily, when they 
are first used. 

A property "<logger>.useParentHandlers". This defines a boolean value. By 
default every logger calls its parent in addition to handling the logging 
message itself, this often result in messages being handled by the root logger 
as well. When setting this property to false a Handler needs to be configured 
for this logger otherwise no logging messages are delivered. 

A property "config". This property is intended to allow arbitrary configuration 
code to be run. The property defines a whitespace or comma separated list of 
class names. A new instance will be created for each named class. The default 
constructor of each class may execute arbitrary code to update the logging 
configuration, such as setting logger levels, adding handlers, adding filters, 
etc. 

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. 



*java.lang.String_java.util.logging.LogManager.LOGGING_MXBEAN_NAME*

String representation of the (|javax.management.ObjectName|) for 
(|java.util.logging.LoggingMXBean|) . 



*java.util.logging.LogManager()*

protected 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. 


*java.util.logging.LogManager.addLogger(Logger)*

public synchronized boolean addLogger(java.util.logging.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. 


    logger - the new logger. 

    Returns: true if the argument logger was registered successfully, false if a logger of 
             that name already exists. 

*java.util.logging.LogManager.addPropertyChangeListener(PropertyChangeListener)*

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)
  throws |java.lang.SecurityException|
         
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. 


    l - event listener 

*java.util.logging.LogManager.checkAccess()*

public void checkAccess()
  throws |java.lang.SecurityException|
         
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. 



*java.util.logging.LogManager.getLogger(String)*

public synchronized |java.util.logging.Logger| getLogger(java.lang.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. 


    name - name of the logger 

    Returns: matching logger or null if none is found 

*java.util.logging.LogManager.getLoggerNames()*

public synchronized |java.util.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. 



    Returns: enumeration of logger name strings 

*java.util.logging.LogManager.getLoggingMXBean()*

public static synchronized |java.util.logging.LoggingMXBean| getLoggingMXBean()

Returns LoggingMXBean for managing loggers. The LoggingMXBean can also obtained 
from the platform 
<tt>MBeanServer</tt>(|java.lang.management.ManagementFactory|) method. 



    Returns: a {@link LoggingMXBean} object. 

*java.util.logging.LogManager.getLogManager()*

public static |java.util.logging.LogManager| getLogManager()

Return the global LogManager object. 



*java.util.logging.LogManager.getProperty(String)*

public |java.lang.String| getProperty(java.lang.String name)

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


    name - property name 

    Returns: property value 

*java.util.logging.LogManager.readConfiguration()*

public void readConfiguration()
  throws |java.io.IOException|
         |java.lang.SecurityException|
         
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. 



*java.util.logging.LogManager.readConfiguration(InputStream)*

public void readConfiguration(java.io.InputStream ins)
  throws |java.io.IOException|
         |java.lang.SecurityException|
         
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. 


    ins - stream to read properties from 

*java.util.logging.LogManager.removePropertyChangeListener(PropertyChangeListener)*

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)
  throws |java.lang.SecurityException|
         
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. 


    l - event listener (can be null) 

*java.util.logging.LogManager.reset()*

public void reset()
  throws |java.lang.SecurityException|
         
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.