Package org.apache.sis.util.logging

# Class LoggerFactory<L>

Object
LoggerFactory<L>

Type Parameters:
  `L` - the type of loggers used for the implementation backend. This is the type used by external frameworks like Log4J.

public abstract class LoggerFactory<L> extends Object
A factory for Java `Logger` wrapping an other logging framework. This factory is used only when an application wants to redirect SIS logs to an other framework than JDK logging. An instance of `LoggerFactory` can be registered to SIS in two ways:

- By declaring the fully qualified classname of the `LoggerFactory` implementation in the `META-INF/services/org​.apache​.sis​.util​.logging​.LoggerFactory` file. Note that the `sis-logging-commons​.jar` and `sis-logging-log4j​.jar` files provide such declaration.
- By explicit invocation of `Logging​.setLoggerFactory(LoggerFactory)` at application initialization time.

The `getLogger(String)` method shall return some `Logger` subclass (typically `LoggerAdapter`) which forwards directly all log methods to the other framework.

## Thread safety

This base class is safe for multi-threads usage. Subclasses registered in `META-INF/services/` shall make sure that any overridden methods remain safe to call from multiple threads.

Since:
  0.3
See Also:
  - `Logging`
  - `LoggerAdapter`

Defined in the `sis-utility` module

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `LoggerFactory(Class<L> loggerClass)`
  Creates a new factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected abstract L`
  `getImplementation(String name)`
  Returns the implementation to use for the logger of the specified name.
  `Class<L>`
  `getImplementationClass()`
  Returns the base class of objects to be returned by `getImplementation(String)`.
  `Logger`
  `getLogger(String name)`
  Returns the logger of the specified name, or `null` if the JDK logging framework should be used.
  `abstract String`
  `getName()`
  Returns the name of the logging framework.
  `protected abstract L`
  `unwrap(Logger logger)`
  Returns the implementation wrapped by the specified logger, or `null` if none.
  `protected abstract Logger`
  `wrap(String name, L implementation)`
  Wraps the specified implementation in a JDK logger.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### LoggerFactory

    protected LoggerFactory(Class<L> loggerClass)
    Creates a new factory.
    Parameters:
      `loggerClass` - The class of the wrapped logger.

- ## Method Details

  - ### getName

    public abstract String getName()
    Returns the name of the logging framework.
    Returns:
      the logging framework name.

  - ### getLogger

    public Logger getLogger(String name)
    Returns the logger of the specified name, or `null` if the JDK logging framework should be used.
    Parameters:
      `name` - the name of the logger.
    Returns:
      the logger, or `null` if the JDK logging framework should be used.

  - ### getImplementationClass

    public Class<L> getImplementationClass()
    Returns the base class of objects to be returned by `getImplementation(String)`. The class depends on the underlying logging framework (Log4J, SLF4J, etc.).
    Returns:
      the type of loggers used for the implementation backend.

  - ### getImplementation

    protected abstract L getImplementation(String name)
    Returns the implementation to use for the logger of the specified name. The object to be returned depends on the logging framework (Log4J, SLF4J, etc.). If the target framework redirects logging events to JDK logging, then this method shall return `null` since we should not use wrapper at all.
    Parameters:
      `name` - the name of the logger.
    Returns:
      the logger as an object of the target logging framework (Log4J, SLF4J, etc.), or `null` if the target framework would redirect to the JDK logging framework.

  - ### wrap

    protected abstract Logger wrap(String name, L implementation)
    Wraps the specified implementation in a JDK logger.
    Parameters:
      `name` - the name of the logger.
      `implementation` - an implementation returned by `getImplementation(String)`.
    Returns:
      a new logger wrapping the specified implementation.

  - ### unwrap

    protected abstract L unwrap(Logger logger)
    Returns the implementation wrapped by the specified logger, or `null` if none. If the specified logger is not an instance of the expected class, then this method should returns `null`.
    Parameters:
      `logger` - the logger to test.
    Returns:
      the implementation wrapped by the specified logger, or `null` if none.