Package org.djutils.logger

Class CategoryLogger

java.lang.Object
org.djutils.logger.CategoryLogger
public final class CategoryLogger extends Object
The CategoryLogger can log for specific Categories. The way to call the logger for messages that always need to be logged, such as an error with an exception is: 
 CategoryLogger.always().error(exception, "Parameter {} did not initialize correctly", param1.toString());
It is also possible to indicate the category / categories for the message, which will only be logged if at least one of the indicated categories is turned on with addLogCategory() or setLogCategories(), or if one of the added or set LogCategories is LogCategory.ALL: 
 CategoryLogger.filter(Cat.BASE).debug("Parameter {} initialized correctly", param1.toString());

Copyright (c) 2018-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

Author:
Alexander Verbraeck

  • Field Details

    • DEFAULT_MESSAGE_FORMAT

      public static final String DEFAULT_MESSAGE_FORMAT
      The default message format.
      See Also:

    • DELEGATE_LOGGER

      public static final CategoryLogger.DelegateLogger DELEGATE_LOGGER
      The delegate logger instance that does the actual logging work, after a positive filter outcome.

    • NO_LOGGER

      public static final CategoryLogger.DelegateLogger NO_LOGGER
      The delegate logger that returns immediately after a negative filter outcome.

  • Method Details

    • create

      protected static void create()
      Create a new logger for the system console. Note that this REPLACES current writers. Note that the initial LogCategory is LogCategory.ALL, so all categories will be logged. This category has to be explicitly removed (or new categories have to be set) to log a limited set of categories.

    • setAllLogMessageFormat

      public static void setAllLogMessageFormat(String newMessageFormat)
      Set a new logging format for the message lines of all writers. The default message format is:
      {class_name}.{method}:{line} {message|indent=4}

      A few popular placeholders that can be used:
      - {class} Fully-qualified class name where the logging request is issued
      - {class_name} Class name (without package) where the logging request is issued
      - {date} Date and time of the logging request, e.g. {date:yyyy-MM-dd HH:mm:ss} [SimpleDateFormat]
      - {level} Logging level of the created log entry
      - {line} Line number from where the logging request is issued
      - {message} Associated message of the created log entry
      - {method} Method name from where the logging request is issued
      - {package} Package where the logging request is issued
      Because all individual writers get a log level at which they log, the overall log level in the Configurator is Level.TRACE, which means that all messages are passed through on a generic level and it is up to the individual Writers to decide when to log.
      Parameters:
      newMessageFormat - String; the new formatting pattern to use for all registered writers
      See Also:

    • setAllLogLevel

      public static void setAllLogLevel(org.pmw.tinylog.Level newLevel)
      Set a new logging level for all registered writers. Because all individual writers get a log level at which they log, the overall log level in the Configurator is Level.TRACE, which means that all messages are passed through on a generic level and it is up to the individual Writers to decide when to log.
      Parameters:
      newLevel - Level; the new log level for all registered writers

    • setLogMessageFormat

      public static void setLogMessageFormat(org.pmw.tinylog.writers.Writer writer, String newMessageFormat)
      Set a new logging format for the message lines of a writer. The default message format is:
      {class_name}.{method}:{line} {message|indent=4}

      A few popular placeholders that can be used:
      - {class} Fully-qualified class name where the logging request is issued
      - {class_name} Class name (without package) where the logging request is issued
      - {date} Date and time of the logging request, e.g. {date:yyyy-MM-dd HH:mm:ss} [SimpleDateFormat]
      - {level} Logging level of the created log entry
      - {line} Line number from where the logging request is issued
      - {message} Associated message of the created log entry
      - {method} Method name from where the logging request is issued
      - {package} Package where the logging request is issued
      Parameters:
      writer - Writer; the writer to change the message format for
      newMessageFormat - String; the new formatting pattern to use for all registered writers
      See Also:

    • setLogLevel

      public static void setLogLevel(org.pmw.tinylog.writers.Writer writer, org.pmw.tinylog.Level newLevel)
      Set a new logging level for one of the registered writers.
      Parameters:
      writer - Writer; the writer to change the log level for
      newLevel - Level; the new log level for the writer

    • addWriter

      public static boolean addWriter(org.pmw.tinylog.writers.Writer writer)
      Add a writer to the CategoryLogger, using the current default for the log level and for the message format.
      Parameters:
      writer - Writer; the writer to add
      Returns:
      boolean; true when the writer was added; false when the writer was already registered

    • removeWriter

      public static boolean removeWriter(org.pmw.tinylog.writers.Writer writer)
      Remove a writer from the CategoryLogger.
      Parameters:
      writer - Writer; the writer to remove
      Returns:
      boolean; true if the writer was removed; false if the writer was not registered (and thus could not be removed)

    • getWriters

      public static ImmutableSet<org.pmw.tinylog.writers.Writer> getWriters()
      Return the set of all registered writers.
      Returns:
      ImmutableSet<Writer>; the set of all registered writers

    • addLogCategory

      public static void addLogCategory(LogCategory logCategory)
      Add a category to be logged to the Writers.
      Parameters:
      logCategory - LogCategory; the LogCategory to add

    • removeLogCategory

      public static void removeLogCategory(LogCategory logCategory)
      Remove a category to be logged to the Writers.
      Parameters:
      logCategory - LogCategory; the LogCategory to remove

    • setLogCategories

      public static void setLogCategories(LogCategory... newLogCategories)
      Set the categories to be logged to the Writers.
      Parameters:
      newLogCategories - LogCategory...; the LogCategories to set, replacing the previous ones

    • getLogCategories

      public static ImmutableSet<LogCategory> getLogCategories()
      Return the set of all log categories (cached immutable copy).
      Returns:
      ImmutableSet<Writer>; the set of all registered writers

    • always

      public static CategoryLogger.DelegateLogger always()
      The "pass" filter that will result in always trying to log.
      Returns:
      the logger that tries to execute logging (delegateLogger)

    • filter

      public static CategoryLogger.DelegateLogger filter(LogCategory logCategory)
      Check whether the provided category needs to be logged. Note that when LogCategory.ALL is contained in the categories, filter will return true.
      Parameters:
      logCategory - LogCategory; the category to check for.
      Returns:
      the logger that either tries to log (delegateLogger), or returns without logging (noLogger)

    • filter

      public static CategoryLogger.DelegateLogger filter(LogCategory... logCategories)
      Check whether the provided categories contain one or more categories that need to be logged. Note that when LogCategory.ALL is contained in the categories, filter will return true.
      Parameters:
      logCategories - LogCategory...; elements or array with the categories to check for
      Returns:
      the logger that either tries to log (delegateLogger), or returns without logging (noLogger)

    • filter

      public static CategoryLogger.DelegateLogger filter(Set<LogCategory> logCategories)
      Check whether the provided categories contain one or more categories that need to be logged. Note that when LogCategory.ALL is contained in the categories, filter will return true.
      Parameters:
      logCategories - Set<LogCategory>; the categories to check for
      Returns:
      the logger that either tries to log (delegateLogger), or returns without logging (noLogger)

    • when

      public static CategoryLogger.DelegateLogger when(boolean condition)
      The conditional filter that will result in the usage of a DelegateLogger.
      Parameters:
      condition - boolean; the condition that should be evaluated
      Returns:
      the logger that further processes logging (DelegateLogger)

    • when

      public static CategoryLogger.DelegateLogger when(BooleanSupplier supplier)
      The conditional filter that will result in the usage of a DelegateLogger.
      Parameters:
      supplier - BooleanSupplier; the function evaluating the condition
      Returns:
      the logger that further processes logging (DelegateLogger)