Package org.silverpeas.kernel.logging

Interface SilverLogger

All Known Implementing Classes:
SysLogger
public interface SilverLogger
The custom logger for Silverpeas. It abstracts the concrete logging mechanism that will be used in runtime and it provides additional capabilities for the specific use in Silverpeas.

This custom logger is an adapter to a concrete underlying logging backend to use to log messages. The logging backend can be the logging subsystem of the used application server or a tiers logging framework. With the adapter it can then be easy to switch from an implementation to the other without impacting the logging use in the code of Silverpeas.

Each logger is identified by a namespace and belongs to an hierarchical tree of loggers rooted to the silverpeas namespace. The namespace of a logger defines the position of the logger in the tree: a logger with as namespace silverpeas.kernel is a child of the root Silverpeas logger. When a logger of a given namespace isn't found, then it is the configuration of the nearest defined parent logger that is used (logging level and handler). In Silverpeas, the handlers (aka the snippet of codes that handles the messages into logs) are predefined by configuration and cannot be modified programmatically.

The convention mapping between the namespace of a logger and the package name of an object that logs messages is that all packages rooted to the package org.silverpeas are mapped, each of them, to a namespace of identical name rooted to the Silverpeas root namespace silverpeas. For others packages, the namespace is the package fully qualified name.

An implementation of this interface must be a wrapper of a concrete logging mechanism and instances of the implementation must be manufactured by the SilverLoggerFactory factory.

Author:
mmoquillon

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    debug(String message, Object... parameters)
    Logs a debugging message with the specified parameters.
    default void
    debug(Supplier<String> messageSupplier)
    Logs an debugging message with the specified parameters.
    default void
    error(String message, Object... parameters)
    Logs an error message with the specified parameters.
    default void
    error(String message, Object[] parameters, Throwable error)
    Logs an error message with the specified parameters.
    default void
    error(String message, Throwable error)
    Logs an error message with the specified parameters.
    default void
    error(Throwable error)
    Logs an error message with the specified parameters.
    Level
    getLevel()
    Gets the log Level of this Logger.
    static SilverLogger
    getLogger(Object object)
    Gets a logger for the specified object.
    static SilverLogger
    getLogger(String module)
    Gets the logger that is defined for the specified logging namespace.
    String
    getNamespace()
    Gets the namespace of this logger.
    default void
    info(String message, Object... parameters)
    Logs an information message with the specified parameters.
    boolean
    isLoggable(Level level)
    Checks if a message of the given level would actually be logged by this logger.
    void
    log(Level level, String message, Object... parameters)
    Logs a message at the specified level, with the specified parameters if any.
    void
    log(Level level, String message, Object[] parameters, Throwable error)
    Logs a message at the specified level, with the specified parameters if any and with a Throwable object if any.
    void
    setLevel(Level level)
    Sets the log level specifying which message levels will be logged by this logger.
    default SilverLogger
    silent(Throwable error)
    Logs silently the specified error.
    default void
    warn(String message, Object... parameters)
    Logs a warning message with the specified parameters.
    default void
    warn(Throwable error)
    Logs a warning message with the specified parameters.

  • Method Details

    • getLogger

      static SilverLogger getLogger(String module)
      Gets the logger that is defined for the specified logging namespace. The logger getting is delegated to a SilverLoggerProvider instance.
      Parameters:
      module - a logging namespace. It is the name or a category under which the messages will be log.
      Returns:
      a logger instance provided by a SilverLoggerProvider instance.
      See Also:

    • getLogger

      static SilverLogger getLogger(Object object)
      Gets a logger for the specified object. The logger getting is delegated to a SilverLoggerProvider instance.
      Parameters:
      object - the object from which the logging namespace is determined. The logging namespace is found from the package name of the object. In Silverpeas, each logger namespace matches a package name, starting from the * silverpeas subpackage: for a package org.silverpeas.core.io, there is a logger with the namespace silverpeas.core.io.
      Returns:
      a logger instance provided by a SilverLoggerProvider instance.
      See Also:

    • getNamespace

      String getNamespace()
      Gets the namespace of this logger. Each logger is defined by a unique dot separated namespace.
      Returns:
      the namespace of this logger.

    • getLevel

      Level getLevel()
      Gets the log Level of this Logger. If no level was explicitly set for his logger, its effective level is then inherited from its parent.
      Returns:
      the level of this logger.

    • setLevel

      void setLevel(Level level)
      Sets the log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded. If the new level is null, it means that this node should inherit its level from its nearest ancestor with a specific (non-null) level value.
      Parameters:
      level - the new value for the log level (may be null).

    • isLoggable

      boolean isLoggable(Level level)
      Checks if a message of the given level would actually be logged by this logger. This check is based on the Loggers effective level, which may be inherited from its parent.
      Parameters:
      level - a logging level.
      Returns:
      true if a message of the given level would actually be logged. False otherwise.

    • log

      void log(Level level, String message, Object[] parameters, Throwable error)
      Logs a message at the specified level, with the specified parameters if any and with a Throwable object if any. If the logger is currently enabled for the given message level then a corresponding logging record is created and forwarded to all the registered output handlers objects.
      Parameters:
      level - the level of the message to log.
      message - the message to log.
      parameters - zero, one or more parameters to the message. Shouldn't be null.
      error - an error to log with the message.

    • log

      void log(Level level, String message, Object... parameters)
      Logs a message at the specified level, with the specified parameters if any.
      Parameters:
      level - the level of the message to log.
      message - the message to log.
      parameters - zero, one or more parameters to the message.

    • error

      default void error(String message, Object... parameters)
      Logs an error message with the specified parameters.
      Parameters:
      message - the message to log.
      parameters - zero, one or more parameters to set to the message

    • error

      default void error(Throwable error)
      Logs an error message with the specified parameters.
      Parameters:
      error - the cause of the error.

    • error

      default void error(String message, Throwable error)
      Logs an error message with the specified parameters.
      Parameters:
      message - the message to log.
      error - the cause of the error.

    • error

      default void error(String message, Object[] parameters, Throwable error)
      Logs an error message with the specified parameters.
      Parameters:
      message - the message to log.
      parameters - zero, one or more parameters to set to the message
      error - the cause of the error.

    • warn

      default void warn(String message, Object... parameters)
      Logs a warning message with the specified parameters.
      Parameters:
      message - the message to log.
      parameters - zero, one or more parameters to set to the message

    • warn

      default void warn(Throwable error)
      Logs a warning message with the specified parameters.

      Only the message of the error will be logged.

      Parameters:
      error - the cause of the error.

    • info

      default void info(String message, Object... parameters)
      Logs an information message with the specified parameters.
      Parameters:
      message - the message to log.
      parameters - zero, one or more parameters to set to the message

    • debug

      default void debug(String message, Object... parameters)
      Logs a debugging message with the specified parameters.
      Parameters:
      message - the message to log.
      parameters - zero, one or more parameters to set to the message

    • debug

      default void debug(Supplier<String> messageSupplier)
      Logs an debugging message with the specified parameters. The message is computed by a function that will be invoked only if the actual logger level is higher or equal than the message level.

      Usually, debugging message are computed by executing codes that shouldn't be ran in a nominal execution context. In order to avoid this code to be executed when the logger level is lower than the debug level, it can be written within a function whose the invocation is left to the logger responsibility.

      Parameters:
      messageSupplier - a function that will computed the message to log.

    • silent

      default SilverLogger silent(Throwable error)
      Logs silently the specified error. The message is actually wiped out. This method is mainly dedicated to explicitly indicate the error is expected in some well-defined circumstances; it is a computation branch in the nominal execution flow.

      Be caution by using this method; it is more efficient to use the if-else condition than the try-catch instruction to perform a default treatment on error cases. This method is to be used when a method marked as throwing an exception is invoked and for which the exception is, in the context of the invocation, can be expected.

      Parameters:
      error - the error to wipe out.
      Returns:
      the logger itself.