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);
}
