Class Logger

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.

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.

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.

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.

public void entering(String sourceClass,
                     String sourceMethod)

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

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

public void exiting(String sourceClass,
                    String sourceMethod)

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

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.

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.

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.

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.

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.

public Filter getFilter()

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.

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.

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.

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.

public String getName()

Returns the name of this logger.

Returns:

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

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.

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.

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.

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.

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.

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.

public void log(Level level,
                String message)

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

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

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

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.

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

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

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.

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.

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.

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.

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

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

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