Package org.apache.sis.util.logging

## Class Logging

- Object
- - Static
  - - Logging

-     public final class Logging
      extends Static

  A set of utilities method for configuring loggings in SIS. Library implementers should fetch their loggers using the `getLogger(String)` static method defined in this `Logging` class rather than the one defined in the standard `Logger` class, in order to give SIS a chance to redirect the logs to an other framework like Commons-logging or Log4J.

  This class provides also some convenience static methods, including:

  - `log(Class, String, LogRecord)` for setting the logger name, source class name and source method name of the given record before to log it.
  - `unexpectedException(Logger, Class, String, Throwable)` for reporting an anomalous but nevertheless non-fatal exception.
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static Logger` | `getLogger​(Class<?> source)` | Returns a logger for the package of the specified class.
    `static Logger` | `getLogger​(String name)` | Returns a logger for the specified name.
    `static LoggerFactory<?>` | `getLoggerFactory()` | Returns the factory used for obtaining `Logger` instances, or `null` if none.
    `static boolean` | `ignorableException​(Logger logger, Class<?> classe, String method, Throwable error)` | Invoked when an ignorable error occurred.
    `static void` | `log​(Class<?> classe, String method, LogRecord record)` | Logs the given record to the logger associated to the given class.
    `static boolean` | `recoverableException​(Logger logger, Class<?> classe, String method, Throwable error)` | Invoked when a recoverable error occurred.
    `static void` | `setLoggerFactory​(LoggerFactory<?> factory)` | Sets a new factory to use for obtaining `Logger` instances.
    `static boolean` | `severeException​(Logger logger, Class<?> classe, String method, Throwable error)` | Invoked when a severe error occurred.
    `static boolean` | `unexpectedException​(Logger logger, Class<?> classe, String method, Throwable error)` | Invoked when an unexpected error occurred.

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### setLoggerFactory

          @Configuration
          public static void setLoggerFactory​(LoggerFactory<?> factory)

      Sets a new factory to use for obtaining `Logger` instances. If the given `factory` argument is `null` (the default), then the standard Logging framework will be used.
      Limitation
      SIS classes typically declare a logger constant like below:

      >     public static final Logger LOGGER = Logging.getLogger("the.logger.name");

      Factory changes will take effect only if this method is invoked before the initialization of such classes.
      Parameters:
        `factory` - the new logger factory, or `null` if none.

    - #### getLoggerFactory

          public static LoggerFactory<?> getLoggerFactory()

      Returns the factory used for obtaining `Logger` instances, or `null` if none.
      Returns:
        the current logger factory, or `null` if none.

    - #### getLogger

          public static Logger getLogger​(String name)

      Returns a logger for the specified name. If a logger factory has been set, then this method first asks to the factory. This rule gives SIS a chance to redirect logging events to commons-logging or some equivalent framework. Only if no factory was found or if the factory choose to not redirect the loggings, then this method delegate to `Logger​.getLogger(name)`.
      Parameters:
        `name` - the logger name.
      Returns:
        a logger for the specified name.

    - #### getLogger

          public static Logger getLogger​(Class<?> source)

      Returns a logger for the package of the specified class. This convenience method invokes `getLogger(String)` with the package name of the given class taken as the logger name.
      Parameters:
        `source` - the class which will emit a logging message.
      Returns:
        a logger for the specified class.
      Since:
        1.0

    - #### log

          public static void log​(Class<?> classe,
                                 String method,
                                 LogRecord record)

      Logs the given record to the logger associated to the given class. This convenience method performs the following steps:
      - Unconditionally set the source class name to the canonical name of the given class;
      - Unconditionally set the source method name to the given value;
      - Get the logger for the logger name if specified, or for the `classe` package name otherwise;
      - Set the logger name of the given record, if not already set;
      - Log the modified record.
      Parameters:
        `classe` - the class for which to obtain a logger.
        `method` - the name of the method which is logging a record.
        `record` - the record to log.

    - #### unexpectedException

          public static boolean unexpectedException​(Logger logger,
                                                    Class<?> classe,
                                                    String method,
                                                    Throwable error)

      Invoked when an unexpected error occurred. This method logs a message at `Level​.WARNING` to the specified logger. The originating class name and method name can optionally be specified. If any of them is `null`, then it will be inferred from the error stack trace as described below.
      Recommended usage: explicit value for class and method names are preferred to automatic inference for the following reasons:
      - Automatic inference is not 100% reliable, since the Java Virtual Machine is free to omit stack frame in optimized code.
      - When an exception occurred in a private method used internally by a public method, we sometime want to log the warning for the public method instead, since the user is not expected to know anything about the existence of the private method. If a developer really want to know about the private method, the stack trace is still available anyway.
      If the `classe` or `method` arguments are null, then the originating class name and method name are inferred from the given `error` using the first stack trace element for which the class name is inside a package or sub-package of the same name than the logger name.
      Example: if the logger name is `"org​.apache​.sis​.image"`, then this method will uses the first stack trace element where the fully qualified class name starts with `"org​.apache​.sis​.image"` or `"org​.apache​.sis​.image​.io"`, but not `"org​.apache​.sis​.imageio"`.
      Parameters:
        `logger` - where to log the error, or `null` for inferring a default value from other arguments.
        `classe` - the class where the error occurred, or `null` for inferring a default value from other arguments.
        `method` - the method where the error occurred, or `null` for inferring a default value from other arguments.
        `error` - the error, or `null` if none.
      Returns:
        `true` if the error has been logged, or `false` if the given `error` was null or if the logger does not log anything at `Level​.WARNING`.
      See Also:
        `recoverableException(Logger, Class, String, Throwable)`, `severeException(Logger, Class, String, Throwable)`

    - #### recoverableException

          public static boolean recoverableException​(Logger logger,
                                                     Class<?> classe,
                                                     String method,
                                                     Throwable error)

      Invoked when a recoverable error occurred. This method is similar to `unexpectedException(…)` except that it does not log the stack trace and uses a lower logging level.
      Parameters:
        `logger` - where to log the error, or `null` for inferring a default value from other arguments.
        `classe` - the class where the error occurred, or `null` for inferring a default value from other arguments.
        `method` - the method name where the error occurred, or `null` for inferring a default value from other arguments.
        `error` - the error, or `null` if none.
      Returns:
        `true` if the error has been logged, or `false` if the given `error` was null or if the logger does not log anything at `Level​.FINE`.
      See Also:
        `unexpectedException(Logger, Class, String, Throwable)`, `severeException(Logger, Class, String, Throwable)`

    - #### ignorableException

          public static boolean ignorableException​(Logger logger,
                                                   Class<?> classe,
                                                   String method,
                                                   Throwable error)

      Invoked when an ignorable error occurred. This method is similar to `unexpectedException(…)` except that it uses a lower logging level.
      Parameters:
        `logger` - where to log the error, or `null` for inferring a default value from other arguments.
        `classe` - the class where the error occurred, or `null` for inferring a default value from other arguments.
        `method` - the method name where the error occurred, or `null` for inferring a default value from other arguments.
        `error` - the error, or `null` if none.
      Returns:
        `true` if the error has been logged, or `false` if the given `error` was null or if the logger does not log anything at `Level​.FINER`.
      Since:
        1.0

    - #### severeException

          public static boolean severeException​(Logger logger,
                                                Class<?> classe,
                                                String method,
                                                Throwable error)

      Invoked when a severe error occurred. This method is similar to `unexpectedException` except that it logs the message at the `SEVERE` level.
      Parameters:
        `logger` - where to log the error, or `null` for inferring a default value from other arguments.
        `classe` - the class where the error occurred, or `null` for inferring a default value from other arguments.
        `method` - the method name where the error occurred, or `null` for inferring a default value from other arguments.
        `error` - the error, or `null` if none.
      Returns:
        `true` if the error has been logged, or `false` if the given `error` was null or if the logger does not log anything at `Level​.SEVERE`.
      See Also:
        `unexpectedException(Logger, Class, String, Throwable)`, `recoverableException(Logger, Class, String, Throwable)`