java.util.logging

Class Logger

public class Logger extends Object

A Logger is used for logging information about events. Usually, there is a seprate logger for each subsystem or component, although there is a shared instance for components that make only occasional use of the logging framework.

It is common to name a logger after the name of a corresponding Java package. Loggers are organized into a hierarchical namespace; for example, the logger "org.gnu.foo" is the parent of logger "org.gnu.foo.bar".

A logger for a named subsystem can be obtained through {@link java.util.logging.Logger#getLogger(java.lang.String)}. However, only code which has been granted the permission to control the logging infrastructure will be allowed to customize that logger. Untrusted code can obtain a private, anonymous logger through {@link #getAnonymousLogger()} if it wants to perform any modifications to the logger.

FIXME: Write more documentation.

Field Summary
static Logger	global A logger provided to applications that make only occasional use of the logging framework, typically early prototypes.

Constructor Summary
protected	Logger(String name, String resourceBundleName) Constructs a Logger for a subsystem.

Method Summary
void	addHandler(Handler handler) Adds a handler to the set of handlers that get notified when a log record is to be published.
void	config(String message) Logs a message with severity level CONFIG.
void	entering(String sourceClass, String sourceMethod)
void	entering(String sourceClass, String sourceMethod, Object param)
void	entering(String sourceClass, String sourceMethod, Object[] params)
void	exiting(String sourceClass, String sourceMethod)
void	exiting(String sourceClass, String sourceMethod, Object result)
void	fine(String message) Logs a message with severity level FINE.
void	finer(String message) Logs a message with severity level FINER.
void	finest(String message) Logs a message with severity level FINEST.
static Logger	getAnonymousLogger() Creates a new, unnamed logger.
static Logger	getAnonymousLogger(String resourceBundleName) Creates a new, unnamed logger.
Filter	getFilter()
Handler[]	getHandlers() Returns the handlers currently registered for this Logger.
Level	getLevel() Returns the severity level threshold for this `Handler`.
static Logger	getLogger(String name) Finds a registered logger for a subsystem, or creates one in case no logger has been registered yet.
static Logger	getLogger(String name, String resourceBundleName) Finds a registered logger for a subsystem, or creates one in case no logger has been registered yet.
String	getName() Returns the name of this logger.
Logger	getParent() Returns the parent of this logger.
ResourceBundle	getResourceBundle() Returns the resource bundle that is being used for localizing messages.
String	getResourceBundleName() Returns the name of the resource bundle that is being used for localizing messages.
boolean	getUseParentHandlers() Returns whether or not this Logger forwards log records to handlers registered for its parent loggers.
void	info(String message) Logs a message with severity level INFO.
boolean	isLoggable(Level level) Returns whether or not a message of the specified level would be logged by this logger.
void	log(LogRecord record) Passes a record to registered handlers, provided the record is considered as loggable both by {@link #isLoggable(Level)} and a possibly installed custom {@link #setFilter(Filter) filter}.
void	log(Level level, String message)
void	log(Level level, String message, Object param)
void	log(Level level, String message, Object[] params)
void	log(Level level, String message, Throwable thrown)
void	logp(Level level, String sourceClass, String sourceMethod, String message)
void	logp(Level level, String sourceClass, String sourceMethod, String message, Object param)
void	logp(Level level, String sourceClass, String sourceMethod, String message, Object[] params)
void	logp(Level level, String sourceClass, String sourceMethod, String message, Throwable thrown)
void	logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message)
void	logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object param)
void	logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object[] params)
void	logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Throwable thrown)
void	removeHandler(Handler handler) Removes a handler from the set of handlers that get notified when a log record is to be published.
void	setFilter(Filter filter)
void	setLevel(Level level) Sets the severity level threshold for this `Handler`.
void	setParent(Logger parent) Sets the parent of this logger.
void	setUseParentHandlers(boolean useParentHandlers) Sets whether or not this Logger forwards log records to handlers registered for its parent loggers.
void	severe(String message) Logs a message with severity level SEVERE, indicating a serious failure that prevents normal program execution.
void	throwing(String sourceClass, String sourceMethod, Throwable thrown)
void	warning(String message) Logs a message with severity level WARNING, indicating a potential problem that does not prevent normal program execution.

Field Detail

global

public static final Logger global

A logger provided to applications that make only occasional use of the logging framework, typically early prototypes. Serious products are supposed to create and use their own Loggers, so they can be controlled individually.

Constructor Detail

Logger

protected Logger(String name, String resourceBundleName)

Constructs a Logger for a subsystem. Most applications do not need to create new Loggers explicitly; instead, they should call the static factory methods {@link #getLogger(java.lang.String,java.lang.String) getLogger} (with ResourceBundle for localization) or {@link #getLogger(java.lang.String) getLogger} (without ResourceBundle), respectively.

Parameters: name the name for the logger, for example "java.awt" or "com.foo.bar". The name should be based on the name of the package issuing log records and consist of dot-separated Java identifiers. resourceBundleName the name of a resource bundle for localizing messages, or null to indicate that messages do not need to be localized.

Throws: java.util.MissingResourceException if resourceBundleName is not null and no such bundle could be located.

Method Detail

addHandler

public void addHandler(Handler handler)

Adds a handler to the set of handlers that get notified when a log record is to be published.

Parameters: handler the handler to be added.

Throws: NullPointerException if handler is null. SecurityException if this logger is not anonymous, a security manager exists, and the caller is not granted the permission to control the logging infrastructure by having LoggingPermission("control"). Untrusted code can obtain an anonymous logger through the static factory method {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.

config

public void config(String message)

Logs a message with severity level CONFIG. {@link Level#CONFIG} is intended for static configuration messages, for example about the windowing environment, the operating system version, etc.

Parameters: message the message text, also used as look-up key if the logger is localizing messages with a resource bundle. While it is possible to pass null, this is not recommended, since a logging message without text is unlikely to be helpful.

entering

public void entering(String sourceClass, String sourceMethod)

entering

public void entering(String sourceClass, String sourceMethod, Object param)

entering

public void entering(String sourceClass, String sourceMethod, Object[] params)

exiting

public void exiting(String sourceClass, String sourceMethod)

exiting

public void exiting(String sourceClass, String sourceMethod, Object result)

fine

public void fine(String message)

Logs a message with severity level FINE. {@link Level#FINE} is intended for messages that are relevant for developers using the component generating log messages. Examples include minor, recoverable failures, or possible inefficiencies.

finer

public void finer(String message)

Logs a message with severity level FINER. {@link Level#FINER} is intended for rather detailed tracing, for example entering a method, returning from a method, or throwing an exception.

finest

public void finest(String message)

Logs a message with severity level FINEST. {@link Level#FINEST} is intended for highly detailed tracing, for example reaching a certain point inside the body of a method.

getAnonymousLogger

public static Logger getAnonymousLogger()

Creates a new, unnamed logger. Unnamed loggers are not registered in the namespace of the LogManager, and no special security permission is required for changing their state. Therefore, untrusted applets are able to modify their private logger instance obtained through this method.

The parent of the newly created logger will the the root logger, from which the level threshold and the handlers are inherited.

getAnonymousLogger

public static Logger getAnonymousLogger(String resourceBundleName)

The parent of the newly created logger will the the root logger, from which the level threshold and the handlers are inherited.

Parameters: resourceBundleName the name of a resource bundle for localizing messages, or null to indicate that messages do not need to be localized.

Throws: java.util.MissingResourceException if resourceBundleName is not null and no such bundle could be located.

getFilter

public Filter getFilter()

getHandlers

public Handler[] getHandlers()

Returns the handlers currently registered for this Logger. When a log record has been deemed as being loggable, it will be passed to all registered handlers for publication. In addition, if the logger uses parent handlers (see {@link #getUseParentHandlers() getUseParentHandlers} and {@link #setUseParentHandlers(boolean) setUseParentHandlers}, the log record will be passed to the parent's handlers.

getLevel

public Level getLevel()

Returns the severity level threshold for this Handler. All log records with a lower severity level will be discarded; a log record of the same or a higher level will be published unless an installed Filter decides to discard it.

Returns: the severity level below which all log messages will be discarded, or null if the logger inherits the threshold from its parent.

getLogger

public static Logger getLogger(String name)

Finds a registered logger for a subsystem, or creates one in case no logger has been registered yet.

Returns: a logger for the subsystem specified by name that does not localize messages.

Throws: IllegalArgumentException if a logger for the subsystem identified by name has already been created, but uses a a resource bundle for localizing messages. NullPointerException if name is null.

getLogger

public static Logger getLogger(String name, String resourceBundleName)

Finds a registered logger for a subsystem, or creates one in case no logger has been registered yet.

If a logger with the specified name has already been registered, the behavior depends on the resource bundle that is currently associated with the existing logger.

If the existing logger uses the same resource bundle as specified by resourceBundleName, the existing logger is returned.
If the existing logger currently does not localize messages, the existing logger is modified to use the bundle specified by resourceBundleName. The existing logger is then returned. Therefore, all subsystems currently using this logger will produce localized messages from now on.
If the existing logger already has an associated resource bundle, but a different one than specified by resourceBundleName, an IllegalArgumentException is thrown.

Parameters: name the name for the logger, for example "java.awt" or "org.gnu.foo". The name should be based on the name of the package issuing log records and consist of dot-separated Java identifiers. resourceBundleName the name of a resource bundle for localizing messages, or null to indicate that messages do not need to be localized.

Returns: a logger for the subsystem specified by name.

Throws: java.util.MissingResourceException if resourceBundleName is not null and no such bundle could be located. IllegalArgumentException if a logger for the subsystem identified by name has already been created, but uses a different resource bundle for localizing messages. NullPointerException if name is null.

getName

public String getName()

Returns the name of this logger.

Returns: the name of this logger, or null if the logger is anonymous.

getParent

public Logger getParent()

Returns the parent of this logger. By default, the parent is assigned by the LogManager by inspecting the logger's name.

Returns: the parent of this logger (as detemined by the LogManager by inspecting logger names), the root logger if no other logger has a name which is a prefix of this logger's name, or null for the root logger.

getResourceBundle

public ResourceBundle getResourceBundle()

Returns the resource bundle that is being used for localizing messages.

Returns: the resource bundle used for localizing messages, or null if the parent's resource bundle is used for this purpose.

getResourceBundleName

public String getResourceBundleName()

Returns the name of the resource bundle that is being used for localizing messages.

Returns: the name of the resource bundle used for localizing messages, or null if the parent's resource bundle is used for this purpose.

getUseParentHandlers

public boolean getUseParentHandlers()

Returns whether or not this Logger forwards log records to handlers registered for its parent loggers.

Returns: false if this Logger sends log records merely to Handlers registered with itself; true if this Logger sends log records not only to Handlers registered with itself, but also to those Handlers registered with parent loggers.

info

public void info(String message)

Logs a message with severity level INFO. {@link Level#INFO} is intended for purely informational messages that do not indicate error or warning situations. In the default logging configuration, INFO messages will be written to the system console. For this reason, the INFO level should be used only for messages that are important to end users and system administrators. Messages at this level should be understandable to an inexperienced, non-technical user.

isLoggable

public boolean isLoggable(Level level)

Returns whether or not a message of the specified level would be logged by this logger.

Throws: NullPointerException if level is null.

log

public void log(LogRecord record)

Passes a record to registered handlers, provided the record is considered as loggable both by {@link #isLoggable(Level)} and a possibly installed custom {@link #setFilter(Filter) filter}.

If the logger has been configured to use parent handlers, the record will be forwarded to the parent of this logger in addition to being processed by the handlers registered with this logger.

The other logging methods in this class are convenience methods that merely create a new LogRecord and pass it to this method. Therefore, subclasses usually just need to override this single method for customizing the logging behavior.

Parameters: record the log record to be inspected and possibly forwarded.

log

public void log(Level level, String message)

log

public void log(Level level, String message, Object param)

log

public void log(Level level, String message, Object[] params)

log

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

logp

public void logp(Level level, String sourceClass, String sourceMethod, String message)

logp

public void logp(Level level, String sourceClass, String sourceMethod, String message, Object param)

logp

public void logp(Level level, String sourceClass, String sourceMethod, String message, Object[] params)

logp

public void logp(Level level, String sourceClass, String sourceMethod, String message, Throwable thrown)

logrb

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message)

logrb

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object param)

logrb

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object[] params)

logrb

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Throwable thrown)

removeHandler

public void removeHandler(Handler handler)

Removes a handler from the set of handlers that get notified when a log record is to be published.

Parameters: handler the handler to be removed.

Throws: SecurityException if this logger is not anonymous, a security manager exists, and the caller is not granted the permission to control the logging infrastructure by having LoggingPermission("control"). Untrusted code can obtain an anonymous logger through the static factory method {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}. NullPointerException if handler is null.

setFilter

public void setFilter(Filter filter)

setLevel

public void setLevel(Level level)

Sets the severity level threshold for this Handler. All log records with a lower severity level will be discarded immediately. A log record of the same or a higher level will be published unless an installed Filter decides to discard it.

Parameters: level the severity level below which all log messages will be discarded, or null to indicate that the logger should inherit the threshold from its parent.

setParent

public void setParent(Logger parent)

Sets the parent of this logger. Usually, applications do not call this method directly. Instead, the LogManager will ensure that the tree of loggers reflects the hierarchical logger namespace. Basically, this method should not be public at all, but the GNU implementation follows the API specification.

Throws: NullPointerException if parent is null. SecurityException if this logger is not anonymous, a security manager exists, and the caller is not granted the permission to control the logging infrastructure by having LoggingPermission("control"). Untrusted code can obtain an anonymous logger through the static factory method {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.

setUseParentHandlers

public void setUseParentHandlers(boolean useParentHandlers)

Sets whether or not this Logger forwards log records to handlers registered for its parent loggers.

Parameters: useParentHandlers false to let this Logger send log records merely to Handlers registered with itself; true to let this Logger send log records not only to Handlers registered with itself, but also to those Handlers registered with parent loggers.

severe

public void severe(String message)

Logs a message with severity level SEVERE, indicating a serious failure that prevents normal program execution. Messages at this level should be understandable to an inexperienced, non-technical end user. Ideally, they explain in simple words what actions the user can take in order to resolve the problem.

throwing

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

warning

public void warning(String message)

Logs a message with severity level WARNING, indicating a potential problem that does not prevent normal program execution. Messages at this level should be understandable to an inexperienced, non-technical end user. Ideally, they explain in simple words what actions the user can take in order to resolve the problem.