java.util.logging
Class Logger

java.lang.Object
  java.util.logging.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 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 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(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	log(LogRecord record) Passes a record to registered handlers, provided the record is considered as loggable both by isLoggable(Level) and a possibly installed custom filter.
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.

Methods inherited from class java.lang.Object

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

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)
          throws MissingResourceException

Constructs a Logger for a subsystem. Most applications do not need to create new Loggers explicitly; instead, they should call the static factory methods getLogger (with ResourceBundle for localization) or 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:

MissingResourceException - if resourceBundleName is not null and no such bundle could be located.

Method Detail

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.

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.

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:

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.

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)
                                 throws MissingResourceException

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.

Parameters:

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

Throws:

MissingResourceException - if resourceBundleName is not null and no such bundle could be located.

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.

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.

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.

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.

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.

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

getFilter

public Filter getFilter()

setFilter

public void setFilter(Filter filter)
               throws SecurityException

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

getName

public String getName()

Returns the name of this logger.

Returns:

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

log

public void log(LogRecord record)

Passes a record to registered handlers, provided the record is considered as loggable both by isLoggable(Level) and a possibly installed custom 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)

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)

throwing

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

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.

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.

See Also:

Level.SEVERE

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.

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.

See Also:

Level.WARNING

info

public void info(String message)

Logs a message with severity level INFO. 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.

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.

config

public void config(String message)

Logs a message with severity level CONFIG. 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.

fine

public void fine(String message)

Logs a message with severity level FINE. 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.

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.

finer

public void finer(String message)

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

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.

finest

public void finest(String message)

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

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.

addHandler

public void addHandler(Handler handler)
                throws SecurityException

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

removeHandler

public void removeHandler(Handler handler)
                   throws SecurityException

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

NullPointerException - if handler is null.

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 getUseParentHandlers and setUseParentHandlers, the log record will be passed to the parent's handlers.

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.

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.

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

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.

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