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.
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.
handler
- the handler to be added.
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.
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.
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.
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.
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.
resourceBundleName
- the name of a resource bundle for localizing
messages, or null
to indicate that messages do
not need to be localized.
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.
- 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.
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.
- a logger for the subsystem specified by
name
that
does not localize messages.
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.
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.
- a logger for the subsystem specified by
name
.
getName
public String getName()
Returns the name of this logger.
- 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.
- 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.
- 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.
- 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.
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.
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.
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.
record
- the log record to be inspected and possibly forwarded.
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.
handler
- the handler to be removed.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.