A Logger object is used
to emit log messages. Logger does not have a
public constructor, but there are several ways to obtain a
Logger object to use in your code:
Typically, applications call the static getLogger(
) method to create or lookup a named
Logger within a hierarchy of named loggers.
Loggers have dot-separated hierarchical names, which should be based
on the name of the class or package that uses them. Loggers obtained
in this way inherit their logging level, resource bundle (for
localization), and Handler objects from their
ancestors in the hierarchy and, ultimately, from the root
Logger defined by the global
LogManager.
Applets that require a Logger with no security
restrictions should use the static getAnonymousLogger(
) method to create an unnamed Logger
that is not part of the hierarchy of named Logger
objects managed by the LogManager. A
Logger created by this method has the
LogManager root logger as its parent, and inherits
the logging level and handlers of that root logger.
Finally, the static Logger.global field refers to
a pre-defined Logger named
"global"; programmers may find this
pre-defined Logger convenient during the early
stages of application development, but it should not be used in
production code.
Once a suitable Logger has been obtained, there
are a variety of methods that can be used to create a log message:
The log( ) methods log a specified message at the
specified level, with optional parameters that can be used in message
localization. These methods examine the call stack and make an
attempt to determine the class and method name from which the method
is emitted. Because of code optimization and just-in-time compilation
techniques, however, they may not always be able to determine this
information.
The logp( ) ("log
precise") methods are like the log(
) methods but allow you to explicitly specify the name of
the class and method that are emitting the log message.
The logrb( ) methods are like the logp(
) methods, but additionally take the name of a resource
bundle to use for localizing the message.
entering( ), exiting( ), and
tHRowing( ) are convenience methods for emitting
log messages that trace the execution of a program. These methods use
a logging level of Level.FINER. Note that there
are variants of entering( ) and exiting(
) that allow specification of method arguments and return
values.
Finally, Logger defines a set of easy-to-use
convenience methods for logging a simple message at a specific
logging level. These methods have the same names as the logging
levels: severe( ), warning( ),
info( ), config( ),
fine( ), finer( ),
finest( ).
A Logger has an associated logging
Level, and discards any log messages with a
severity lower than this. The severity level is initialized from the
system configuration file, which is usually the desired behavior. You
can explicitly override this setting with setLevel(
). You might want to do this if you created the
Logger with getAnonymousLogger(
) and have read the desired logging level from a
configuration file of your own. If level-based filtering of log
messages is not sufficient, you can associate a
Filter with your Logger by
calling setFilter. If you do this, any log
messages rejected by the Filter will be discarded.
A Logger sends its log messages to any
Handler objects that have been registered with
addHandler( ). Call getHandlers(
) to obtain an array of all registered handlers, and call
removeHandler( ) to de-register a handler. By
default, all log messages are also sent to the handlers of the parent
logger and any other ancestor loggers. Since all named and anonymous
loggers have the LogManager root logger as a
parent or ancestor, all loggers by default send their log messages to
the handlers defined in the system logging configuration file. See
LogManager for details. If you do not want a
Logger to use the handlers of its ancestors, pass
false to setUseParentHandlers(
).
getLogger( ) and getAnonymousLogger(
) allow you to specify the name of a
java.util.ResourceBundle for use in localizing log
messages, and logrb( ) allows you to specify the
name of a resource bundle to use to localize a specific log message.
If a resource bundle is specified for the Logger
or for a specific log message, then the message argument to the
various logging methods is treated not as a literal message but
instead as a localization key for which a localized version is to be
looked up in the resource bundle. As part of the localization, any
parameters, such as those specified by the
param1 and
params arguments to the log(
) method are substituted into the localized message string
as per java.text.MessageFormat. (Note, however
that this localization and formatting is not performed by the Logger
itself: instead, it simply stores the
ResourceBundle and parameters in the
LogRecord. It is the Formatter
associated with the output Handler object that
actually performs the localization.)
All the methods of this class are threadsafe and do not require
external synchronization.
public class
Logger {
// Protected Constructors
protected
Logger (String
name , String
resourceBundleName );
// Public Constants
public static final Logger
global ;
// Public Class Methods
public static Logger
getAnonymousLogger ( ); synchronized
public static Logger
getAnonymousLogger (String
resourceBundleName ); synchronized
public static Logger
getLogger (String
name ); synchronized
public static Logger
getLogger (String
name , String
resourceBundleName ); synchronized
// Public Instance Methods
public void
addHandler (Handler
handler ) throws SecurityException; synchronized
public void
config (String
msg );
public void
entering (String
sourceClass , String
sourceMethod );
public void
entering (String
sourceClass , String
sourceMethod , Object
param1 );
public void
entering (String
sourceClass , String
sourceMethod , Object[ ]
params );
public void
exiting (String
sourceClass , String
sourceMethod );
public void
exiting (String
sourceClass , String
sourceMethod , Object
result );
public void
fine (String
msg );
public void
finer (String
msg );
public void
finest (String
msg );
public Filter
getFilter ( );
public Handler[ ]
getHandlers ( ); synchronized
public Level
getLevel ( );
public String
getName ( );
public Logger
getParent ( );
public java.util.ResourceBundle
getResourceBundle ( );
public String
getResourceBundleName ( );
public boolean
getUseParentHandlers ( ); synchronized
public void
info (String
msg );
public boolean
isLoggable (Level
level );
public void
log (LogRecord
record );
public void
log (Level
level , String
msg );
public void
log (Level
level , String
msg , Throwable
thrown );
public void
log (Level
level , String
msg , Object
param1 );
public void
log (Level
level , String
msg , Object[ ]
params );
public void
logp (Level
level , String
sourceClass , String
sourceMethod ,
String
msg );
public void
logp (Level
level , String
sourceClass , String
sourceMethod ,
String
msg , Object
param1 );
public void
logp (Level
level , String
sourceClass , String
sourceMethod ,
String
msg , Object[ ]
params );
public void
logp (Level
level , String
sourceClass , String
sourceMethod ,
String
msg , Throwable
thrown );
public void
logrb (Level
level , String
sourceClass , String
sourceMethod ,
String
bundleName , String
msg );
public void
logrb (Level
level , String
sourceClass , String
sourceMethod ,
String
bundleName , String
msg , Object
param1 );
public void logrb(Level
level , String
sourceClass , String
sourceMethod ,
String
bundleName , String
msg , Throwable
thrown );
public void
logrb (Level
level , String
sourceClass , String
sourceMethod ,
String
bundleName , String
msg , Object[ ]
params );
public void
removeHandler (Handler
handler ) throws SecurityException; synchronized
public void
setFilter (Filter
newFilter ) throws SecurityException;
public void
setLevel (Level
newLevel ) throws SecurityException;
public void
setParent (Logger
parent );
public void
setUseParentHandlers (boolean
useParentHandlers ); synchronized
public void
severe (String
msg );
public void
throwing (String
sourceClass , String
sourceMethod , Throwable
thrown );
public void
warning (String
msg );
}