java.lang

Class System.LoggerFinder

java.lang.Object

java.lang.System.LoggerFinder

Enclosing class:

System

public abstract static class System.LoggerFinder
extends Object

The LoggerFinder service is responsible for creating, managing, and configuring loggers to the underlying framework it uses.

A logger finder is a concrete implementation of this class that has a zero-argument constructor and implements the abstract methods defined by this class. The loggers returned from a logger finder are capable of routing log messages to the logging backend this provider supports. A given invocation of the Java Runtime maintains a single system-wide LoggerFinder instance that is loaded as follows:

• First it finds any custom LoggerFinder provider using the ServiceLoader facility with the system class loader.
• If no LoggerFinder provider is found, the system default LoggerFinder implementation will be used.

An application can replace the logging backend even when the java.logging module is present, by simply providing and declaring an implementation of the System.LoggerFinder service.

Default Implementation

The system default LoggerFinder implementation uses java.util.logging as the backend framework when the java.logging module is present. It returns a logger instance that will route log messages to a java.util.logging.Logger. Otherwise, if java.logging is not present, the default implementation will return a simple logger instance that will route log messages of INFO level and above to the console (System.err).

Logging Configuration

Logger instances obtained from the LoggerFinder factory methods are not directly configurable by the application. Configuration is the responsibility of the underlying logging backend, and usually requires using APIs specific to that backend.

For the default LoggerFinder implementation using java.util.logging as its backend, refer to java.util.logging for logging configuration. For the default LoggerFinder implementation returning simple loggers when the java.logging module is absent, the configuration is implementation dependent.

Usually an application that uses a logging framework will log messages through a logger facade defined (or supported) by that framework. Applications that wish to use an external framework should log through the facade associated with that framework.

A system class that needs to log messages will typically obtain a System.Logger instance to route messages to the logging framework selected by the application.

Libraries and classes that only need loggers to produce log messages should not attempt to configure loggers by themselves, as that would make them dependent from a specific implementation of the LoggerFinder service.

In addition, when a security manager is present, loggers provided to system classes should not be directly configurable through the logging backend without requiring permissions.
It is the responsibility of the provider of the concrete LoggerFinder implementation to ensure that these loggers are not configured by untrusted code without proper permission checks, as configuration performed on such loggers usually affects all applications in the same Java Runtime.

Message Levels and Mapping to backend levels

A logger finder is responsible for mapping from a System.Logger.Level to a level supported by the logging backend it uses.
The default LoggerFinder using java.util.logging as the backend maps System.Logger levels to java.util.logging levels of corresponding severity - as described in Logger.Level.

Since:

9

See Also:

System, System.Logger

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LoggerFinder() Creates a new instance of LoggerFinder.

Method Summary

Modifier and Type	Method and Description
System.Logger	getLocalizedLogger(String name, ResourceBundle bundle, Class<?> caller) Returns a localizable instance of Logger for the given caller.
abstract System.Logger	getLogger(String name, Class<?> caller) Returns an instance of Logger for the given caller.
static System.LoggerFinder	getLoggerFinder() Returns the LoggerFinder instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

LoggerFinder

protected LoggerFinder()

Creates a new instance of LoggerFinder.

Implementation Note:

It is recommended that a LoggerFinder service implementation does not perform any heavy initialization in its constructor, in order to avoid possible risks of deadlock or class loading cycles during the instantiation of the service provider.

Throws:

SecurityException - if a security manager is present and its checkPermission method doesn't allow the RuntimePermission("loggerFinder").

Method Detail

getLogger

public abstract System.Logger getLogger(String name,
                                        Class<?> caller)

Returns an instance of Logger for the given caller.

Parameters:

name - the name of the logger.

caller - the class for which the logger is being requested; can be null.

Returns:

a logger suitable for the given caller's use.

Throws:

NullPointerException - if name is null or caller is null.

SecurityException - if a security manager is present and its checkPermission method doesn't allow the RuntimePermission("loggerFinder").

getLocalizedLogger

public System.Logger getLocalizedLogger(String name,
                                        ResourceBundle bundle,
                                        Class<?> caller)

Returns a localizable instance of Logger for the given caller. The returned logger will use the provided resource bundle for message localization.

Implementation Requirements:

By default, this method calls this.getLogger(name, caller) to obtain a logger, then wraps that logger in a System.Logger instance where all methods that do not take a ResourceBundle as parameter are redirected to one which does - passing the given bundle for localization. So for instance, a call to Logger.log(Level.INFO, msg) will end up as a call to Logger.log(Level.INFO, bundle, msg, (Object[])null) on the wrapped logger instance. Note however that by default, string messages returned by Supplier<String> will not be localized, as it is assumed that such strings are messages which are already constructed, rather than keys in a resource bundle.

An implementation of LoggerFinder may override this method, for example, when the underlying logging backend provides its own mechanism for localizing log messages, then such a LoggerFinder would be free to return a logger that makes direct use of the mechanism provided by the backend.

Parameters:

name - the name of the logger.

bundle - a resource bundle; can be null.

caller - the class for which the logger is being requested.

Returns:

an instance of Logger which will use the provided resource bundle for message localization.

Throws:

NullPointerException - if name is null or caller is null.

SecurityException - if a security manager is present and its checkPermission method doesn't allow the RuntimePermission("loggerFinder").

getLoggerFinder

public static System.LoggerFinder getLoggerFinder()

Returns the LoggerFinder instance. There is one single system-wide LoggerFinder instance in the Java Runtime. See the class specification of how the LoggerFinder implementation is located and loaded.

Returns:

the LoggerFinder instance.

Throws:

SecurityException - if a security manager is present and its checkPermission method doesn't allow the RuntimePermission("loggerFinder").