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 getLogger(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

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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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 Details

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 Details

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.

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.

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

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.

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 getUseParentHandlers and 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.
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.

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

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(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)

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.

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

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.

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.

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.

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.

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

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

Logger.java -- a class for logging messages Copyright (C) 2002, 2004, 2006, 2007 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.