Logger (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.log, class: Logger

Package freemarker.log

# Class Logger

java.lang.Object
freemarker.log.Logger

public abstract class Logger extends Object
Delegates logger creation to an actual logging library (this was written before SLF4J, or even Apache Commons Logging was widespread). This is used by FreeMarker internally for logging.

By default, it looks for logger classes via reflection, in the below order, and picks the first one that it founds:

1. SLF4J: Skipped for backward compatibility, except under GraalVM native, and FreeMarker 2.4.x (planned).
2. Apache Commons Logging: Skipped for backward compatibility, except under GraalVM native, and FreeMarker 2.4.x (planned).
3. Log4J
4. Avalon LogKit
5. JUL (i.e., `java.util.logging`)

Furthermore, if you have `log4j-over-slf4j` properly installed (means, you have no real Log4j in your class path, and SLF4J has a backing implementation like `logback-classic`), then FreeMarker will use SLF4J directly instead of Log4j (since FreeMarker 2.3.22). (This trick is, of course, irrelevant if SLF4J lookup is not skipped.)

If the auto-detection rule described above doesn't give you the result that you want, see `SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static int`
  `LIBRARY_AUTO`
  Enum value used for `selectLoggerLibrary(int)`; indicates auto-selection as described in the class documentation of `Logger()`.
  `static int`
  `LIBRARY_AVALON`
  Deprecated.
  Avalon LogKit support will be removed sometimes in the future.
  `static int`
  `LIBRARY_COMMONS`
  Enum value used for `selectLoggerLibrary(int)`; indicates that Apache commons-logging should be used.
  `static int`
  `LIBRARY_JAVA`
  Enum value used for `selectLoggerLibrary(int)`; indicates that `java.util.logging` should be used.
  `static int`
  `LIBRARY_LOG4J`
  Enum value used for `selectLoggerLibrary(int)`; indicates that Log4J should be used.
  `static String`
  `LIBRARY_NAME_AUTO`
  "org.freemarker.loggerLibrary" property value; indicates auto-selection as described in the class documentation of `Logger()`.
  `static String`
  `LIBRARY_NAME_AVALON`
  Deprecated.
  Avalon LogKit support will be removed sometimes in the future.
  `static String`
  `LIBRARY_NAME_COMMONS_LOGGING`
  "org.freemarker.loggerLibrary" property value; indicates that Apache commons-logging should be used.
  `static String`
  `LIBRARY_NAME_JUL`
  "org.freemarker.loggerLibrary" property value; indicates that `java.util.logging` should be used.
  `static String`
  `LIBRARY_NAME_LOG4J`
  "org.freemarker.loggerLibrary" property value; indicates that Log4J should be used.
  `static String`
  `LIBRARY_NAME_NONE`
  "org.freemarker.loggerLibrary" property value; indicates that no logging should occur.
  `static String`
  `LIBRARY_NAME_SLF4J`
  "org.freemarker.loggerLibrary" property value; indicates that SLF4J should be used.
  `static int`
  `LIBRARY_NONE`
  Enum value used for `selectLoggerLibrary(int)`; indicates that no logging should occur.
  `static int`
  `LIBRARY_SLF4J`
  Constant used with `selectLoggerLibrary(int)`; indicates that SLF4J should be used.
  `static String`
  `SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY`
  The "org.freemarker.loggerLibrary" system property is used to select a logger library explicitly, rather than relying on automatic selection.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Logger()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `debug​(String message)`
  Logs a debugging message.
  `abstract void`
  `debug​(String message, Throwable t)`
  Logs a debugging message with accompanying throwable.
  `abstract void`
  `error​(String message)`
  Logs an error message.
  `abstract void`
  `error​(String message, Throwable t)`
  Logs an error message with accompanying throwable.
  `static Logger`
  `getLogger​(String category)`
  Returns a logger for the specified category.
  `abstract void`
  `info​(String message)`
  Logs an informational message.
  `abstract void`
  `info​(String message, Throwable t)`
  Logs an informational message with accompanying throwable.
  `abstract boolean`
  `isDebugEnabled()`
  Returns true if this logger will log debug messages.
  `abstract boolean`
  `isErrorEnabled()`
  Returns true if this logger will log error messages.
  `abstract boolean`
  `isFatalEnabled()`
  Returns true if this logger will log fatal error messages.
  `abstract boolean`
  `isInfoEnabled()`
  Returns true if this logger will log informational messages.
  `abstract boolean`
  `isWarnEnabled()`
  Returns true if this logger will log warning messages.
  `static void`
  `selectLoggerLibrary​(int libraryEnum)`
  Deprecated.
  This method isn't reliable, unless you can somehow ensure that you access the FreeMarker classes first; use the "org.freemarker.loggerLibrary" Java system property instead, like `java ... -Dorg.freemarker.loggerLibrary=slf4j`.
  `static void`
  `setCategoryPrefix​(String prefix)`
  Deprecated.
  This wasn't reliable, unless you can somehow ensure that you access the FreeMarker classes first.
  `abstract void`
  `warn​(String message)`
  Logs a warning message.
  `abstract void`
  `warn​(String message, Throwable t)`
  Logs a warning message with accompanying throwable.

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

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

- ## Field Details

  - ### SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY

    public static final String SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY
    The "org.freemarker.loggerLibrary" system property is used to select a logger library explicitly, rather than relying on automatic selection. You meant to set this system property where the JVM is started, like `java ... -Dorg.freemarker.loggerLibrary=SLF4J`. Setting it from Java code isn't reliable, also it can cause confusion if you override the value set by others with `-D`.

    If the requested logging library is not available, an error will be printed to the stderr, then logging will be disabled.

    The supported values are:

    - "SLF4J": Use SLF4J (recommended)
    - "CommonsLogging": Use Apache Commons Logging.
    - "Log4j": Use Log4j.
    - "JUL": Use `java.util.logging`.
    - "Avalon": Use Avalon LogKit (deprecated)
    - "auto": Use automatic selection (default behavior). See `Logger` class documentation for more.
    - "none": Don't log.
    Since:
      2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_AUTO

    public static final int LIBRARY_AUTO
    Enum value used for `selectLoggerLibrary(int)`; indicates auto-selection as described in the class documentation of `Logger()`.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_AUTO

    public static final String LIBRARY_NAME_AUTO
    "org.freemarker.loggerLibrary" property value; indicates auto-selection as described in the class documentation of `Logger()`. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_NONE

    public static final int LIBRARY_NONE
    Enum value used for `selectLoggerLibrary(int)`; indicates that no logging should occur.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_NONE

    public static final String LIBRARY_NAME_NONE
    "org.freemarker.loggerLibrary" property value; indicates that no logging should occur. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_JAVA

    public static final int LIBRARY_JAVA
    Enum value used for `selectLoggerLibrary(int)`; indicates that `java.util.logging` should be used.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_JUL

    public static final String LIBRARY_NAME_JUL
    "org.freemarker.loggerLibrary" property value; indicates that `java.util.logging` should be used. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_AVALON

    @Deprecated public static final int LIBRARY_AVALON
    Deprecated.
    Avalon LogKit support will be removed sometimes in the future.
    Enum value used for `selectLoggerLibrary(int)`; indicates that Avalon LogKit should be used.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_AVALON

    @Deprecated public static final String LIBRARY_NAME_AVALON
    Deprecated.
    Avalon LogKit support will be removed sometimes in the future.
    "org.freemarker.loggerLibrary" property value; indicates that Avalon LogKit should be used. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_LOG4J

    public static final int LIBRARY_LOG4J
    Enum value used for `selectLoggerLibrary(int)`; indicates that Log4J should be used.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_LOG4J

    public static final String LIBRARY_NAME_LOG4J
    "org.freemarker.loggerLibrary" property value; indicates that Log4J should be used. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_COMMONS

    public static final int LIBRARY_COMMONS
    Enum value used for `selectLoggerLibrary(int)`; indicates that Apache commons-logging should be used.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_COMMONS_LOGGING

    public static final String LIBRARY_NAME_COMMONS_LOGGING
    "org.freemarker.loggerLibrary" property value; indicates that Apache commons-logging should be used. @since 2.3.22
    See Also:
      Constant Field Values

  - ### LIBRARY_SLF4J

    public static final int LIBRARY_SLF4J
    Constant used with `selectLoggerLibrary(int)`; indicates that SLF4J should be used.
    See Also:
      Constant Field Values

  - ### LIBRARY_NAME_SLF4J

    public static final String LIBRARY_NAME_SLF4J
    "org.freemarker.loggerLibrary" property value; indicates that SLF4J should be used. @since 2.3.22
    See Also:
      Constant Field Values

- ## Constructor Details

  - ### Logger

    public Logger()

- ## Method Details

  - ### selectLoggerLibrary

    @Deprecated public static void selectLoggerLibrary​(int libraryEnum) throws ClassNotFoundException
    Deprecated.
    This method isn't reliable, unless you can somehow ensure that you access the FreeMarker classes first; use the "org.freemarker.loggerLibrary" Java system property instead, like `java ... -Dorg.freemarker.loggerLibrary=slf4j`. See `SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY` for more.
    Selects the logger library to use, unless it's already specified by the "org.freemarker.loggerLibrary" system property. Call this early in application initialization phase, before calling any other FreeMarker API-s, since once parts of the FreeMarker library bind to the logging subsystem, the change in this value will have no effect on them.
    Parameters:
      `libraryEnum` - One of `LIBRARY_...` constants. By default, `LIBRARY_AUTO` is used.
    Throws:
      `ClassNotFoundException` - if an explicit logging library is asked for (that is, not -1 or 0) and it's not found in the classpath.

  - ### setCategoryPrefix

    @Deprecated public static void setCategoryPrefix​(String prefix)
    Deprecated.
    This wasn't reliable, unless you can somehow ensure that you access the FreeMarker classes first. As it's not known to be useful for users, consider it removed.
    Sets a category prefix. This prefix is prepended to any logger category name. This makes it possible to have different FreeMarker logger categories on a per-application basis (better said, per-classloader basis). By default the category prefix is the empty string. If you set a non-empty category prefix, be sure to include the trailing separator dot (i.e. "MyApp.") If you want to change the default setting, do it early in application initialization phase, before calling any other FreeMarker API since once various parts of the FreeMarker library bind to the logging subsystem, the change in this value will have no effect on them.

  - ### debug

    public abstract void debug​(String message)
    Logs a debugging message.

  - ### debug

    public abstract void debug​(String message, Throwable t)
    Logs a debugging message with accompanying throwable.

  - ### info

    public abstract void info​(String message)
    Logs an informational message.

  - ### info

    public abstract void info​(String message, Throwable t)
    Logs an informational message with accompanying throwable.

  - ### warn

    public abstract void warn​(String message)
    Logs a warning message.

  - ### warn

    public abstract void warn​(String message, Throwable t)
    Logs a warning message with accompanying throwable.

  - ### error

    public abstract void error​(String message)
    Logs an error message.

  - ### error

    public abstract void error​(String message, Throwable t)
    Logs an error message with accompanying throwable.

  - ### isDebugEnabled

    public abstract boolean isDebugEnabled()
    Returns true if this logger will log debug messages.

  - ### isInfoEnabled

    public abstract boolean isInfoEnabled()
    Returns true if this logger will log informational messages.

  - ### isWarnEnabled

    public abstract boolean isWarnEnabled()
    Returns true if this logger will log warning messages.

  - ### isErrorEnabled

    public abstract boolean isErrorEnabled()
    Returns true if this logger will log error messages.

  - ### isFatalEnabled

    public abstract boolean isFatalEnabled()
    Returns true if this logger will log fatal error messages.

  - ### getLogger

    public static Logger getLogger​(String category)
    Returns a logger for the specified category.
    Parameters:
      `category` - a dot separated hierarchical category name. If a category prefix is in effect, it's prepended to the category name.