freemarker.log

## Class Logger

- java.lang.Object
- - freemarker.log.Logger

    public abstract class Logger
    extends Object

Delegates logger creation to an actual logging library. By default it looks for logger libraries in this order (in FreeMarker 2.3.x): Log4J, Avalon LogKit, JUL (i.e., `java.util.logging`). Prior to FreeMarker 2.4, SLF4J and Apache Commons Logging aren't searched automatically due to backward compatibility constraints. But 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).

If the auto detection sequence describet above doesn't give you the result that you want, see `SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY`.

### Field Summary

Fields
`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 and Description
`Logger()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`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`. See `SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY` for more.
`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.
`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 Detail

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

#### Logger

    public Logger()

### Method Detail

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