Module org.hsqldb
Package org.hsqldb.lib

## Class FrameworkLogger

- java.lang.Object
- - org.hsqldb.lib.FrameworkLogger

-     public class FrameworkLogger
      extends java.lang.Object

  A logging framework wrapper that supports java.util.logging and log4j.

  Logger hierarchies are stored at the Class level. Log4j will be used if the Log4j system (not necessarily config files) are found in the runtime classpath. Otherwise, java.util.logging will be used.

  This is pretty safe because for use cases where multiple hierarchies are desired, classloader hierarchies will effectively isolate multiple class-level Logger hierarchies.

  Sad as it is, the java.util.logging facility lacks the most basic developer-side and configuration-side capabilities. Besides having a non-scalable discovery system, the designers didn't comprehend the need for a level between WARNING and SEVERE! Since we don't want to require log4j in Classpath, we have to live with these constraints.

  As with all the popular logging frameworks, if you want to capture a stack trace, you must use the two-parameters logging methods. I.e., you must also pass a String, or only toString() from your throwable will be captured.

  Usage example:

       private static FrameworkLogger logger =
              FrameworkLogger.getLog(SqlTool.class);
       ...
         logger.finer("Doing something log-worthy");

  The system level property `hsqldb.reconfig_logging=false` is required to avoid configuration of java.util.logging. Otherwise configuration takes place.

  Since:
    1.9.0
  Author:
    Blaine Simpson (blaine dot simpson at admc dot com)

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `clearLoggers​(java.lang.String prefixToZap)` | Frees Logger(s), if any, with the specified category, or that begins with the specified prefix + dot.
    `void` | `enduserlog​(java.util.logging.Level level, java.lang.String message)` |
    `void` | `error​(java.lang.String message)` | This is just a wrapper for FrameworkLogger.warning(), because java.util.logging lacks a method for this critical purpose.
    `void` | `error​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.error(String), but also logs a stack trace.
    `void` | `finer​(java.lang.String message)` |
    `void` | `finer​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.finer(String), but also logs a stack trace.
    `void` | `finest​(java.lang.String message)` |
    `void` | `finest​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.finest(String), but also logs a stack trace.
    `static FrameworkLogger` | `getLog​(java.lang.Class c)` | User's entry-point into this logging system.
    `static FrameworkLogger` | `getLog​(java.lang.Class c, java.lang.String contextId)` | This method just defers to the getLog(Class) method unless default (no local configuration) JDK logging is being used; In that case, this method assures that the returned logger has an associated FileHander using the supplied String identifier.
    `static FrameworkLogger` | `getLog​(java.lang.String s)` | Alternative entry-point into this logging system, for cases where you want to share a single logger instance among multiple classes, or you want to use multiple logger instances from a single class.
    `static FrameworkLogger` | `getLog​(java.lang.String baseId, java.lang.String contextId)` | This method just defers to the getLog(String) method unless default (no local configuration) JDK logging is being used; In that case, this method assures that the returned logger has an associated FileHander using the supplied String identifier.
    `void` | `info​(java.lang.String message)` |
    `void` | `info​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.info(String), but also logs a stack trace.
    `void` | `log​(java.util.logging.Level level, java.lang.String message)` |
    `void` | `log​(java.util.logging.Level level, java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.log(Level, String), but also logs a stack trace.
    `void` | `privlog​(java.util.logging.Level level, java.lang.String message, java.lang.Throwable t, int revertMethods, java.lang.Class skipClass)` | The "priv" prefix is historical.
    `static java.lang.String` | `report()` | Utility method for integrators.
    `void` | `severe​(java.lang.String message)` |
    `void` | `severe​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.severe(String), but also logs a stack trace.
    `void` | `warning​(java.lang.String message)` |
    `void` | `warning​(java.lang.String message, java.lang.Throwable t)` | Just like FrameworkLogger.warning(String), but also logs a stack trace.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### report

          public static java.lang.String report()

      Utility method for integrators. Returns a string representation of the active Logger instance keys.

      Not named similar to 'toString' to avoid ambiguity with instance method toString.

      Returns:
        String

    - #### clearLoggers

          public static void clearLoggers​(java.lang.String prefixToZap)

      Frees Logger(s), if any, with the specified category, or that begins with the specified prefix + dot.

      Note that as of today, this depends on the underlying logging framework implementation to release the underlying Logger instances. JUL in Sun's JVM uses weak references, so that should be fine. Log4j as of today seems to use strong references (and no API hooks to free anything), so this method will probably have little benefit for Log4j.

      Parameters:
        `prefixToZap` - String

    - #### getLog

          public static FrameworkLogger getLog​(java.lang.Class c)

      User's entry-point into this logging system.

      You normally want to work with static (class-level) pointers to logger instances, for performance efficiency. See the class-level JavaDoc for a usage example.

      Parameters:
        `c` - Class
      Returns:
        FrameworkLogger

    - #### getLog

          public static FrameworkLogger getLog​(java.lang.Class c,
                                               java.lang.String contextId)

      This method just defers to the getLog(Class) method unless default (no local configuration) JDK logging is being used; In that case, this method assures that the returned logger has an associated FileHander using the supplied String identifier.
      Parameters:
        `c` - Class
        `contextId` - String
      Returns:
        FrameworkLogger

    - #### getLog

          public static FrameworkLogger getLog​(java.lang.String baseId,
                                               java.lang.String contextId)

      This method just defers to the getLog(String) method unless default (no local configuration) JDK logging is being used; In that case, this method assures that the returned logger has an associated FileHander using the supplied String identifier.
      Parameters:
        `baseId` - String
        `contextId` - String
      Returns:
        FrameworkLogger

    - #### getLog

          public static FrameworkLogger getLog​(java.lang.String s)

      Alternative entry-point into this logging system, for cases where you want to share a single logger instance among multiple classes, or you want to use multiple logger instances from a single class.
      Parameters:
        `s` - String
      Returns:
        FrameworkLogger
      See Also:
        `getLog(Class)`

    - #### log

          public void log​(java.util.logging.Level level,
                          java.lang.String message,
                          java.lang.Throwable t)

      Just like FrameworkLogger.log(Level, String), but also logs a stack trace.
      Parameters:
        `level` - java.util.logging.Level level to filter and log at
        `message` - Message to be logged
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `log(Level, String)`, `Logger.log(Level, String)`, `Level`

    - #### privlog

          public void privlog​(java.util.logging.Level level,
                              java.lang.String message,
                              java.lang.Throwable t,
                              int revertMethods,
                              java.lang.Class skipClass)

      The "priv" prefix is historical. This is for special usage when you need to modify the reported call stack. If you don't know that you want to do this, then you should not use this method.
      Parameters:
        `level` - Level
        `message` - String
        `t` - Throwable
        `revertMethods` - int
        `skipClass` - Class

    - #### enduserlog

          public void enduserlog​(java.util.logging.Level level,
                                 java.lang.String message)

    - #### log

          public void log​(java.util.logging.Level level,
                          java.lang.String message)

      Parameters:
        `level` - java.util.logging.Level level to filter and log at
        `message` - Message to be logged
      See Also:
        `Logger.log(Level, String)`, `Level`

    - #### finer

          public void finer​(java.lang.String message)

      Parameters:
        `message` - Message to be logged
      See Also:
        `Logger.finer(String)`

    - #### warning

          public void warning​(java.lang.String message)

      Parameters:
        `message` - Message to be logged
      See Also:
        `Logger.warning(String)`

    - #### severe

          public void severe​(java.lang.String message)

      Parameters:
        `message` - Message to be logged
      See Also:
        `Logger.severe(String)`

    - #### info

          public void info​(java.lang.String message)

      Parameters:
        `message` - Message to be logged
      See Also:
        `Logger.info(String)`

    - #### finest

          public void finest​(java.lang.String message)

      Parameters:
        `message` - Message to be logged
      See Also:
        `Logger.finest(String)`

    - #### error

          public void error​(java.lang.String message)

      This is just a wrapper for FrameworkLogger.warning(), because java.util.logging lacks a method for this critical purpose.
      Parameters:
        `message` - Message to be logged
      See Also:
        `warning(String)`

    - #### finer

          public void finer​(java.lang.String message,
                            java.lang.Throwable t)

      Just like FrameworkLogger.finer(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `finer(String)`

    - #### warning

          public void warning​(java.lang.String message,
                              java.lang.Throwable t)

      Just like FrameworkLogger.warning(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `warning(String)`

    - #### severe

          public void severe​(java.lang.String message,
                             java.lang.Throwable t)

      Just like FrameworkLogger.severe(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `severe(String)`

    - #### info

          public void info​(java.lang.String message,
                           java.lang.Throwable t)

      Just like FrameworkLogger.info(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `info(String)`

    - #### finest

          public void finest​(java.lang.String message,
                             java.lang.Throwable t)

      Just like FrameworkLogger.finest(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `finest(String)`

    - #### error

          public void error​(java.lang.String message,
                            java.lang.Throwable t)

      Just like FrameworkLogger.error(String), but also logs a stack trace.
      Parameters:
        `message` - String
        `t` - Throwable whose stack trace will be logged.
      See Also:
        `error(String)`