Package org.apache.sis.util.logging

## Class LoggerAdapter

- Object
- - Logger
  - - LoggerAdapter

-     public abstract class LoggerAdapter
      extends Logger

  An adapter that redirect all JDK logging events to an other logging framework. This class redefines the `severe`, `warning`, `info`, `config`, `fine`, `finer` and `finest` methods as abstract ones. Subclasses should implement those methods in order to map JDK logging levels to the backend logging framework.

  All `log` methods are overridden in order to redirect to one of the above-cited methods. Note that this is the opposite approach than the JDK logging framework one, which implements everything on top of `Logger​.log(LogRecord)`. This adapter is defined in terms of `severe` … `finest` methods instead because external frameworks like Commons-logging don't work with `LogRecord`, and sometime provides nothing else than convenience methods equivalent to `severe` … `finest`.

  Restrictions
  Because the configuration is expected to be fully controlled by the external logging framework, every configuration methods inherited from `Logger` are disabled:
  - `addHandler(Handler)` since the handling is performed by the external framework.
  - `setUseParentHandlers(boolean)` since this adapter never delegates to the parent handlers. This is consistent with the previous item and avoid mixing loggings from the external framework with JDK loggings.
  - `setParent(Logger)` since this adapter should not inherits any configuration from a parent logger using the JDK logging framework.
  - `setFilter(Filter)` for keeping this `LoggerAdapter` simple.
  Since `LoggerAdapter`s do not hold any configuration by themselves, it is not strictly necessary to add them to the log manager. The adapters can be created, garbage-collected and recreated again while preserving their behavior since their configuration is entirely contained in the external logging framework.
  Localization
  This logger is always created without resource bundles. Localizations shall be done through explicit calls to `logrb` or `log(LogRecord)` methods. This is sufficient for SIS needs, which performs all localizations through the later. Note that those methods will be slower in this `LoggerAdapter` than the default `Logger` because this adapter localizes and formats records immediately instead of letting the Handler performs this work only if needed.
  Logging levels
  If a log record level is not one of the predefined ones, then this class maps to the first level below the specified one. For example if a log record has some level between `FINE` and `FINER`, then the `finer` method will be invoked. See `isLoggable(Level)` for implementation tips taking advantage of this rule.
  Since:
    0.3
  See Also:
    `Logging`

  Defined in the `sis-utility` module

- - ### Field Summary

    - ### Fields inherited from class Logger

      `global, GLOBAL_LOGGER_NAME`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `LoggerAdapter​(String name)` | Creates a new logger.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addHandler​(Handler handler)` | Do nothing since this logger adapter does not supports handlers.
    `abstract void` | `config​(String message)` | Logs an `CONFIG` message.
    `void` | `entering​(String sourceClass, String sourceMethod)` | Logs a method entry to the debug level.
    `void` | `entering​(String sourceClass, String sourceMethod, Object param)` | Logs a method entry to the debug level with one parameter.
    `void` | `entering​(String sourceClass, String sourceMethod, Object[] params)` | Logs a method entry to the debug level with many parameters.
    `void` | `exiting​(String sourceClass, String sourceMethod)` | Logs a method return to the debug level.
    `void` | `exiting​(String sourceClass, String sourceMethod, Object result)` | Logs a method return to the debug level.
    `abstract void` | `fine​(String message)` | Logs a `FINE` message.
    `abstract void` | `finer​(String message)` | Logs a `FINER` message.
    `abstract void` | `finest​(String message)` | Logs a `FINEST` message.
    `protected Level` | `getDebugLevel()` | Returns the level for `entering(…)`, `exiting(…)` and `throwing(…)` methods.
    `abstract Level` | `getLevel()` | Returns the level for this logger.
    `abstract void` | `info​(String message)` | Logs an `INFO` message.
    `abstract boolean` | `isLoggable​(Level level)` | Returns `true` if the specified level is loggable.
    `void` | `log​(Level level, String message)` | Logs a record at the specified level.
    `void` | `log​(Level level, String message, Object param)` | Logs a record at the specified level.
    `void` | `log​(Level level, String message, Object[] params)` | Logs a record at the specified level.
    `void` | `log​(Level level, String message, Throwable thrown)` | Logs a record at the specified level.
    `void` | `log​(LogRecord record)` | Logs a record.
    `void` | `logp​(Level level, String sourceClass, String sourceMethod, String message)` | Logs a record at the specified level.
    `void` | `logp​(Level level, String sourceClass, String sourceMethod, String message, Object param)` | Logs a record at the specified level.
    `void` | `logp​(Level level, String sourceClass, String sourceMethod, String message, Object[] params)` | Logs a record at the specified level.
    `void` | `logp​(Level level, String sourceClass, String sourceMethod, String message, Throwable thrown)` | Logs a record at the specified level.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, String bundleName, String message)` | Deprecated. JDK 8 has deprecated this method.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object param)` | Deprecated. JDK 8 has deprecated this method.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Object[] params)` | Deprecated. JDK 8 has deprecated this method.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, String bundleName, String message, Throwable thrown)` | Deprecated. JDK 8 has deprecated this method.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, ResourceBundle bundle, String message, Object... params)` | Logs a localizable record at the specified level.
    `void` | `logrb​(Level level, String sourceClass, String sourceMethod, ResourceBundle bundle, String message, Throwable thrown)` | Logs a localizable record at the specified level.
    `void` | `removeHandler​(Handler handler)` | Do nothing since this logger adapter does not support handlers.
    `void` | `setFilter​(Filter filter)` | Do nothing since this logger adapter does not support filters.
    `abstract void` | `setLevel​(Level level)` | Sets the level for this logger.
    `void` | `setParent​(Logger parent)` | Do nothing since this logger adapter does not support arbitrary parents.
    `void` | `setUseParentHandlers​(boolean useParentHandlers)` | Do nothing since this logger never use parent handlers.
    `abstract void` | `severe​(String message)` | Logs a `SEVERE` message.
    `void` | `throwing​(String sourceClass, String sourceMethod, Throwable thrown)` | Logs a method failure to the debug level.
    `abstract void` | `warning​(String message)` | Logs a `WARNING` message.

    - ### Methods inherited from class Logger

      `config, fine, finer, finest, getAnonymousLogger, getAnonymousLogger, getFilter, getGlobal, getHandlers, getLogger, getLogger, getName, getParent, getResourceBundle, getResourceBundleName, getUseParentHandlers, info, log, log, logp, logp, logrb, logrb, setResourceBundle, severe, warning`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### LoggerAdapter

          protected LoggerAdapter​(String name)

      Creates a new logger.
      Parameters:
        `name` - the logger name.

  - ### Method Detail

    - #### setLevel

          public abstract void setLevel​(Level level)

      Sets the level for this logger. Subclasses must redirect the call to the external logging framework, or do nothing if the level can not be changed programmatically.
      Overrides:
        `setLevel` in class `Logger`
      Parameters:
        `level` - the new value for the log level (may be null).

    - #### getLevel

          public abstract Level getLevel()

      Returns the level for this logger. Subclasses shall get this level from the external logging framework.
      Overrides:
        `getLevel` in class `Logger`
      Returns:
        the logger's level.

    - #### getDebugLevel

          @Debug
          protected Level getDebugLevel()

      Returns the level for `entering(…)`, `exiting(…)` and `throwing(…)` methods. The default implementation returns `Level​.FINER`, which is consistent with the value used in the JDK logging framework. Subclasses should override this method if a different debug level is wanted.
      Returns:
        the level to use for debugging information.

    - #### isLoggable

          public abstract boolean isLoggable​(Level level)

      Returns `true` if the specified level is loggable.
      Implementation tip
      Given that `Level​.intValue()` for all predefined levels are documented in the `Level` specification and are multiple of 100, given that integer divisions are rounded toward zero and given rule documented in this class javadoc, then logging levels can be efficiently mapped to predefined levels using `switch` statements as below. This statement has good chances to be compiled to the `tableswitch` bytecode rather than `lookupswitch` (see Compiling Switches in The Java Virtual Machine Specification).

      >     public boolean isLoggable(Level level) {
      >         final int n = level.intValue();
      >         switch (n / 100) {
      >             default: {
      >                 // MAX_VALUE is a special value for Level.OFF. Otherwise and
      >                 // if positive, fallthrough since we are greater than SEVERE.
      >                 switch (n) {
      >                     case Integer.MIN_VALUE: return true;  // Level.ALL
      >                     case Integer.MAX_VALUE: return false; // Level.OFF
      >                     default: if (n < 0) return false;
      >                 }
      >             }
      >             case 10: return isSevereEnabled();
      >             case  9: return isWarningEnabled();
      >             case  8: return isInfoEnabled();
      >             case  7: return isConfigEnabled();
      >             case  6: // fallthrough
      >             case  5: return isFineEnabled();
      >             case  4: return isFinerEnabled();
      >             case  3: return isFinestEnabled();
      >             case  2: // fallthrough
      >             case  1: // fallthrough
      >             case  0: return false;
      >         }
      >     }

      Overrides:
        `isLoggable` in class `Logger`
      Parameters:
        `level` - a message logging level.
      Returns:
        `true` if the given message level is currently being logged.

    - #### severe

          public abstract void severe​(String message)

      Logs a `SEVERE` message.
      Overrides:
        `severe` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### warning

          public abstract void warning​(String message)

      Logs a `WARNING` message.
      Overrides:
        `warning` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### info

          public abstract void info​(String message)

      Logs an `INFO` message.
      Overrides:
        `info` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### config

          public abstract void config​(String message)

      Logs an `CONFIG` message.
      Overrides:
        `config` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### fine

          public abstract void fine​(String message)

      Logs a `FINE` message.
      Overrides:
        `fine` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### finer

          public abstract void finer​(String message)

      Logs a `FINER` message.
      Overrides:
        `finer` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### finest

          public abstract void finest​(String message)

      Logs a `FINEST` message.
      Overrides:
        `finest` in class `Logger`
      Parameters:
        `message` - the message to log.

    - #### entering

          public void entering​(String sourceClass,
                               String sourceMethod)

      Logs a method entry to the debug level. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `entering` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of method that is being entered.

    - #### entering

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

      Logs a method entry to the debug level with one parameter. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `entering` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of method that is being entered.
        `param` - parameter to the method being entered.

    - #### entering

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

      Logs a method entry to the debug level with many parameters. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `entering` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of method that is being entered.
        `params` - array of parameters to the method being entered.

    - #### exiting

          public void exiting​(String sourceClass,
                              String sourceMethod)

      Logs a method return to the debug level. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `exiting` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.

    - #### exiting

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

      Logs a method return to the debug level. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `exiting` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `result` - object that is being returned.

    - #### throwing

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

      Logs a method failure to the debug level. Compared to the default `Logger`, this implementation bypass the level check in order to let the backing logging framework do its own check.
      Overrides:
        `throwing` in class `Logger`
      Parameters:
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `thrown` - the Throwable that is being thrown.

    - #### log

          public void log​(LogRecord record)

      Logs a record. The default implementation delegates to one of the `logrb` or `logp(Level,String,String,String)` methods.
      Overrides:
        `log` in class `Logger`
      Parameters:
        `record` - the log record to be published.

    - #### log

          public void log​(Level level,
                          String message)

      Logs a record at the specified level. The default implementation delegates to one of the `severe`, `warning`, `info`, `config`, `fine`, `finer` or `finest` methods according the supplied level.
      Overrides:
        `log` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `message` - the message to log.

    - #### log

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

      Logs a record at the specified level. The default implementation discards the exception and delegates to `log(level, message)`.
      Overrides:
        `log` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `message` - the message to log.
        `thrown` - throwable associated with log message.

    - #### log

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

      Logs a record at the specified level. The default implementation delegates to `log(level, message, params)` where the `params` array is built from the `param` object.
      Overrides:
        `log` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `message` - the message to log.
        `param` - parameter to the method being entered.

    - #### log

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

      Logs a record at the specified level. The default implementation formats the message immediately, then delegates to `log(level, message)`.
      Overrides:
        `log` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `message` - the message to log.
        `params` - array of parameters to the method being entered.

    - #### logp

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

      Logs a record at the specified level. The default implementation discards the source class and source method, then delegates to `log(level, message)`.
      Overrides:
        `logp` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `message` - the message to log.

    - #### logp

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

      Logs a record at the specified level. The default implementation discards the source class and source method, then delegates to `log(level, message, thrown)`.
      Overrides:
        `logp` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `message` - the message to log.
        `thrown` - throwable associated with log message.

    - #### logp

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

      Logs a record at the specified level. The default implementation delegates to `logp(level, sourceClass, sourceMethod, message, params)` where the `params` array is built from the `param` object.

      Note that `sourceClass` and `sourceMethod` will be discarded unless the target `logp` method has been overridden.

      Overrides:
        `logp` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `message` - the message to log.
        `param` - parameter to the method being entered.

    - #### logp

          public void logp​(Level level,
                           String sourceClass,
                           String sourceMethod,
                           String message,
                           Object[] params)

      Logs a record at the specified level. The default implementation formats the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message)`.

      Note that `sourceClass` and `sourceMethod` will be discarded unless the target `logp` method has been overridden.

      Overrides:
        `logp` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `message` - the message to log.
        `params` - array of parameters to the method being entered.

    - #### logrb

          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            ResourceBundle bundle,
                            String message,
                            Object... params)

      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message, params)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundle` - the resource bundle for localizing the message, or `null`.
        `message` - the message to log.
        `params` - array of parameters to the method being entered.
      Since:
        0.5

    - #### logrb

          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            ResourceBundle bundle,
                            String message,
                            Throwable thrown)

      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message, thrown)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundle` - the resource bundle for localizing the message, or `null`.
        `message` - the message to log.
        `thrown` - throwable associated with log message.
      Since:
        0.5

    - #### logrb

          @Deprecated
          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            String bundleName,
                            String message)

      Deprecated.
      JDK 8 has deprecated this method.
      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundleName` - name of resource bundle to localize message, or `null`.
        `message` - the message to log.

    - #### logrb

          @Deprecated
          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            String bundleName,
                            String message,
                            Throwable thrown)

      Deprecated.
      JDK 8 has deprecated this method.
      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message, thrown)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundleName` - name of resource bundle to localize message, or `null`.
        `message` - the message to log.
        `thrown` - throwable associated with log message.

    - #### logrb

          @Deprecated
          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            String bundleName,
                            String message,
                            Object param)

      Deprecated.
      JDK 8 has deprecated this method.
      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message, param)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundleName` - name of resource bundle to localize message, or `null`.
        `message` - the message to log.
        `param` - parameter to the method being entered.

    - #### logrb

          @Deprecated
          public void logrb​(Level level,
                            String sourceClass,
                            String sourceMethod,
                            String bundleName,
                            String message,
                            Object[] params)

      Deprecated.
      JDK 8 has deprecated this method.
      Logs a localizable record at the specified level. The default implementation localizes the message immediately, then delegates to `logp(level, sourceClass, sourceMethod, message, params)`.
      Overrides:
        `logrb` in class `Logger`
      Parameters:
        `level` - one of the message level identifiers.
        `sourceClass` - name of class that issued the logging request.
        `sourceMethod` - name of the method.
        `bundleName` - name of resource bundle to localize message, or `null`.
        `message` - the message to log.
        `params` - array of parameters to the method being entered.

    - #### addHandler

          public void addHandler​(Handler handler)

      Do nothing since this logger adapter does not supports handlers. The configuration should be fully controlled by the external logging framework (e.g. Commons-logging) instead, which is not expected to use `Handler` objects.
      Overrides:
        `addHandler` in class `Logger`
      Parameters:
        `handler` - a logging handler, ignored in default implementation.

    - #### removeHandler

          public void removeHandler​(Handler handler)

      Do nothing since this logger adapter does not support handlers.
      Overrides:
        `removeHandler` in class `Logger`
      Parameters:
        `handler` - a logging handler, ignored in default implementation.

    - #### setUseParentHandlers

          public void setUseParentHandlers​(boolean useParentHandlers)

      Do nothing since this logger never use parent handlers. This is consistent with `addHandler(java​.util​.logging​.Handler)` not allowing to add any handlers, and avoid mixing loggings from the external framework with JDK loggings.
      Overrides:
        `setUseParentHandlers` in class `Logger`
      Parameters:
        `useParentHandlers` - ignored in default implementation.

    - #### setParent

          public void setParent​(Logger parent)

      Do nothing since this logger adapter does not support arbitrary parents. More specifically, it should not inherits any configuration from a parent logger using the JDK logging framework.
      Overrides:
        `setParent` in class `Logger`
      Parameters:
        `parent` - ignored in default implementation.

    - #### setFilter

          public void setFilter​(Filter filter)

      Do nothing since this logger adapter does not support filters. It is difficult to query efficiently the filter in this `LoggerAdapter` architecture (e.g. we would need to make sure that `Filter​.isLoggable(java​.util​.logging​.LogRecord)` is invoked only once even if a `log` call is cascaded into many other `log` calls, and this test must works in multi-threads environment).
      Overrides:
        `setFilter` in class `Logger`
      Parameters:
        `filter` - ignored in default implementation.