public class Logger extends Object
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.
Modifier and Type | Field and Description |
---|---|
static Logger |
global
A logger provided to applications that make only occasional use
of the logging framework, typically early prototypes.
|
Modifier | Constructor and Description |
---|---|
protected |
Logger(String name,
String resourceBundleName)
Constructs a Logger for a subsystem.
|
Modifier and Type | Method and Description |
---|---|
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.
|
protected Logger(String name, String resourceBundleName) throws MissingResourceException
getLogger
(with ResourceBundle for localization) or
getLogger
(without
ResourceBundle), respectively.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.MissingResourceException
- if
resourceBundleName
is not null
and no such bundle could be located.public static Logger getLogger(String name)
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.name
that does not localize messages.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
.public static Logger getLogger(String name, String resourceBundleName)
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.
resourceBundleName
, the existing logger
is returned.resourceBundleName
. The existing logger is then
returned. Therefore, all subsystems currently using this logger
will produce localized messages from now on.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.name
.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
.public static Logger getAnonymousLogger()
The parent of the newly created logger will the the root logger, from which the level threshold and the handlers are inherited.
public static Logger getAnonymousLogger(String resourceBundleName) throws MissingResourceException
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.MissingResourceException
- if
resourceBundleName
is not null
and no such bundle could be located.public String getResourceBundleName()
null
if the parent's resource bundle
is used for this purpose.public ResourceBundle getResourceBundle()
null
if the parent's resource bundle
is used for this purpose.public Level getLevel()
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.null
if the logger inherits
the threshold from its parent.public boolean isLoggable(Level level)
NullPointerException
- if level
is null
.public void setLevel(Level level)
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
.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
.public String getName()
null
if
the logger is anonymous.public void log(LogRecord record)
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.public void logp(Level level, String sourceClass, String sourceMethod, String message, Object param)
public void logp(Level level, String sourceClass, String sourceMethod, String message, Object[] params)
public void logp(Level level, String sourceClass, String sourceMethod, String message, Throwable thrown)
public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message)
public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object param)
public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object[] params)
public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Throwable thrown)
public void severe(String message)
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.Level.SEVERE
public void warning(String message)
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.Level.WARNING
public void info(String message)
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.public void config(String message)
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.public void fine(String message)
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.public void finer(String message)
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.public void finest(String message)
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.public void addHandler(Handler handler) throws SecurityException
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
.public void removeHandler(Handler handler) throws SecurityException
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
.public Handler[] getHandlers()
getUseParentHandlers
and setUseParentHandlers
,
the log record will be passed to the parent's handlers.public boolean getUseParentHandlers()
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.public void setUseParentHandlers(boolean useParentHandlers)
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
.public Logger getParent()
null
for the root logger.public void setParent(Logger parent)
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
.