java.util.logging

Class Logger

java.lang.Object

java.util.logging.Logger

public class Logger
extends Object

A Logger is used to log messages.

Loggers normally have a name, which is an arbitrary string. Named Loggers are created with the factory getLogger(String). This method will either create a new Logger or return a suitable existing Logger, using the name.

It also possible to create anonymous Loggers which are independent from the named Loggers and independent from one another.

Each Logger has an associated Level. This reflects a minimum level that this Logger will care about. If the level is high, the Logger will only care about important messages. When it low, it will care about more messages. Caring means logging. The Level can be changed dynamically, which is useful to augment or diminish the amount of messages that are actually logged.

The names of the logging methods, such as severe(String) or finer(String) denote the importance of the message. Their names match the standard levels given by the class Level. When using one of these methods, the Logger performs a test to compare its own Level and the Level associated with the logging request. If the level of the request is lower than the Logger's level, nothing happens. Otherwise, the Logger forwards the message to a list of Handlers that have been added with the method addHandler(Handler).

Field Summary

Fields

Modifier and Type	Field and Description
protected Level	effectiveLevel This is the real level of the logger.
static String	GLOBAL_LOGGER_NAME This is a name for the global logger.
protected Level	publicLevel This is the level set with setLevel(Level) and returned by getLevel().

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Logger(String name, String resourceBundleName) Protected method to create a logger.

Method Summary

Modifier and Type	Method and Description
void	addHandler(Handler handler) Add a log Handler to the list of Handlers known by the Logger.
void	config(String msg) Log a CONFIG message.
void	fine(String msg) Log a FINE message.
void	finer(String msg) Log a FINER message.
void	finest(String msg) Log a FINEST message.
static Logger	getAnonymousLogger() Each call to this method creates a new Logger.
static Logger	getGlobal() Get the logger with the name Logger.GLOBAL_LOGGER_NAME.
Level	getLevel() Get the current level of this Logger.
static Logger	getLogger(String name) Find or create a logger.
String	getName() Get the name of this logger.
Logger	getParent() Get the parent of this logger.
void	info(String msg) Log an INFO message.
boolean	isLoggable(Level level) Check if a message of the given level would be logged by this Logger.
void	log(Level level, String msg) Log a message, with no arguments.
void	log(Level level, String msg, Throwable thrown) Log a message, with an associated throwable object.
void	log(LogRecord record) Log a LogRecord.
void	removeHandler(Handler handler) Remove the given Handler from the Logger's list.
void	setLevel(Level newLevel) Set the specified Level to the Logger.
void	severe(String msg) Log a SEVERE message.
void	throwing(String sourceClass, String sourceMethod, Throwable thrown) Log a that a method is terminating by throwing an Exception.
void	warning(String msg) Log a WARNING message.

Methods inherited from class java.lang.Object

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

Field Detail

effectiveLevel

protected Level effectiveLevel

This is the real level of the logger.

GLOBAL_LOGGER_NAME

public static final String GLOBAL_LOGGER_NAME

This is a name for the global logger.

See Also:

Constant Field Values

publicLevel

protected Level publicLevel

This is the level set with setLevel(Level) and returned by getLevel(). It may be null, that's why implementation will use the effectiveLevel to determine whether a message must be logged or not.

Constructor Detail

Logger

protected Logger(String name,
                 String resourceBundleName)

Protected method to create a logger. The second parameter is silently ignored, hence any call to this method is equivalent to getLogger(name, null).

Parameters:

name - used to identify the logger.

resourceBundleName - not used.

Method Detail

addHandler

public void addHandler(Handler handler)

Add a log Handler to the list of Handlers known by the Logger.

Parameters:

handler - a new Handler for the Logger

config

public void config(String msg)

Log a CONFIG message.

If the logger is currently enabled for the CONFIG message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

fine

public void fine(String msg)

Log a FINE message.

If the logger is currently enabled for the FINE message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

finer

public void finer(String msg)

Log a FINER message.

If the logger is currently enabled for the FINER message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

finest

public void finest(String msg)

Log a FINEST message.

If the logger is currently enabled for the FINEST message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

getAnonymousLogger

public static Logger getAnonymousLogger()

Each call to this method creates a new Logger. Its level is set to Level.ALL. An anonymous logger is not registered in the LogManager.

Returns:

a new anonymous Logger, whose name is null

getGlobal

public static final Logger getGlobal()

Get the logger with the name Logger.GLOBAL_LOGGER_NAME.

Returns:

the global logger

getLevel

public Level getLevel()

Get the current level of this Logger.

Returns:

the Logger's current level.

getLogger

public static Logger getLogger(String name)

Find or create a logger.

If a logger has already been with the same name, this logger is returned (note that case is not taken into account). Otherwise a new logger is created.

If a new logger is created its log level will be configured based on the LogManager configuration and it will configured to also send logging output to its parent's handlers. It will be registered in the LogManager global namespace.

Note: The LogManager may only retain a weak reference to the newly created logger. It is important to understand that a previously created logger with the given name may be garbage collected at any time if there is no strong reference to the Logger. In particular, this means that two back-to-back calls like getLogger("MyLogger").log(...) may use different Logger objects named "MyLogger" if there is no strong reference to the Logger named "MyLogger" elsewhere in the program.

Parameters:

name - used to identify a logger. Case is not taken into account.

Returns:

a suitable Logger.

Throws:

NullPointerException - if name is null.

getName

public String getName()

Get the name of this logger. It is the name used for its creation or null for anonymous Loggers.

Returns:

the Logger's name (or null for anonymous Loggers).

getParent

public Logger getParent()

Get the parent of this logger.

Returns:

the parent of this logger; null for the root logger

info

public void info(String msg)

Log an INFO message.

If the logger is currently enabled for the INFO message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

isLoggable

public boolean isLoggable(Level level)

Check if a message of the given level would be logged by this Logger. This depends on the Logger current level. If the Logger's current level is lower than 'level', the message would be logged ; otherwise, it would not.

Parameters:

level - a logging Level.

Returns:

true if the message would be logged.

log

public void log(Level level,
                String msg)

Log a message, with no arguments. If the logger is currently enabled for the given message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

level - One of the message level identifiers, e.g. SEVERE

msg - The string message (or a key in the message catalog)

log

public void log(Level level,
                String msg,
                Throwable thrown)

Log a message, with an associated throwable object. If the logger is currently enabled for the given message level then the given message is forwarded to all the registered output Handler objects.

Parameters:

level - One of the message level identifiers, e.g. SEVERE

msg - The string message (or a key in the message catalog)

thrown - The throwable associated with the message

log

public void log(LogRecord record)

Log a LogRecord.

Parameters:

record - the log record to publish

removeHandler

public void removeHandler(Handler handler)

Remove the given Handler from the Logger's list. If the Handlers is null or is not know by the Logger, then the method does nothing.

Parameters:

handler - the Handler to remove

setLevel

public void setLevel(Level newLevel)

Set the specified Level to the Logger. This level specifies which message levels will be logged by this Logger from now on.

Level.OFF can be used to turn off logging.

Parameters:

newLevel - the new Level for the Logger (may be null)

severe

public void severe(String msg)

Log a SEVERE message.

If the logger is currently enabled for the SEVERE message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.

throwing

public void throwing(String sourceClass,
                     String sourceMethod,
                     Throwable thrown)

Log a that a method is terminating by throwing an Exception. The level FINER is used.

Parameters:

sourceClass - name of the class that requested the log

sourceMethod - name of the method inside this class

thrown - the throwable being thrown

warning

public void warning(String msg)

Log a WARNING message.

If the logger is currently enabled for the WARNING message level then the given message is forwarded to all the registered output handler objects.

Parameters:

msg - message to log.