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

    All Methods Instance Methods Abstract Methods Concrete Methods
    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 Detail

    - #### LoggerFactory

          protected LoggerFactory​(Class<L> loggerClass)

      Creates a new factory.
      Parameters:
        `loggerClass` - The class of the wrapped logger.

  - ### Method Detail

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