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.with(Cat.BASE).debug("Parameter {} initialized correctly", param1.toString());

Copyright (c) 2018-2025 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_PATTERN

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

    • DEFAULT_LEVEL

      public static final ch.qos.logback.classic.Level DEFAULT_LEVEL
      The default logging level.

    • CAT_ALWAYS

      public static final LogCategory CAT_ALWAYS
      The log category for the always() method.

  • Method Details

    • always

      public static CategoryLogger.DelegateLogger always()
      Always log to the registered appenders, still observing the default log level.
      Returns:
      the DelegateLogger for method chaining, e.g., CategoryLogger.always().info("message");

    • when

      public static CategoryLogger.DelegateLogger when(boolean condition)
      Only log when the condition is true.
      Parameters:
      condition - the condition to check
      Returns:
      the DelegateLogger for method chaining, e.g., CategoryLogger.when(condition).info("message");

    • when

      public static CategoryLogger.DelegateLogger when(BooleanSupplier booleanSupplier)
      Only log when the boolean supplier provides a true value.
      Parameters:
      booleanSupplier - the supplier that provides true or false
      Returns:
      the DelegateLogger for method chaining, e.g., CategoryLogger.when(() -> condition()).info("message");

    • with

      public static CategoryLogger.DelegateLogger with(LogCategory category)
      Only log when the category has been registered in the CategoryLogger, and with the settings of that logger.
      Parameters:
      category - the category to check
      Returns:
      the DelegateLogger for method chaining, e.g., CategoryLogger.with(Cat.BASE).info("message");

    • addLogCategory

      public static void addLogCategory(LogCategory category)
      Register a log category that can log with the CategoryLogger. Note that unregistered loggers for which you use with() do not log.
      Parameters:
      category - the log category to register.

    • addLogCategory

      public static void addLogCategory(LogCategory category, Class<?> callerBoundary)
      Register a log category that can log with the CategoryLogger, with a 'boundary' class that indicates what to hide in the call stack. Note that unregistered loggers for which you use with() do not log.
      Parameters:
      category - the log category to register.
      callerBoundary - class that defines what to hide in the call stack

    • removeLogCategory

      public static void removeLogCategory(LogCategory category)
      Remove a log category from logging with the CategoryLogger. Note that unregistered loggers for which you use with() do not log.
      Parameters:
      category - the log category to unregister.

    • getAppenders

      public static Collection<ch.qos.logback.core.Appender<ch.qos.logback.classic.spi.ILoggingEvent>> getAppenders(LogCategory category)
      Return the registered appenders for the LogCategory.
      Parameters:
      category - the category to look up
      Returns:
      the appenders for the LogCategory

    • setLogLevel

      public static void setLogLevel(LogCategory category, ch.qos.logback.classic.Level level)
      Set the log category for a single log category.
      Parameters:
      category - the log category
      level - the new log level

    • setLogLevelAll

      public static void setLogLevelAll(ch.qos.logback.classic.Level level)
      Set the log category for all log categories, except ALWAYS.
      Parameters:
      level - the new log level for all log categories, except ALWAYS

    • getLogLevel

      public static ch.qos.logback.classic.Level getLogLevel(LogCategory category)
      Return the log level for a log category.
      Parameters:
      category - the log category
      Returns:
      the log level for the given category

    • setPattern

      public static void setPattern(LogCategory category, String pattern)
      Set the pattern for a single log category. 
       %date{HH:mm:ss.SSS}   Timestamp (default format shown; many options like ISO8601)
 %level / %-5level     Log level (pad to fixed width with %-5level)
 %logger / %logger{0}  Logger name (full or last component only; {n} = # of segments)
 %thread               Thread name
 %msg / %message       The actual log message
 %n                    Platform-specific newline
 %class / %class{1}    Calling class (full or just last segment with {1})
 %method               Calling method
 %line                 Source line number
 %file                 Source file name
 %caller               Shortcut for class, method, file, and line in one
 %marker               SLF4J marker (if present)
 %X{key}               MDC value for given key
 %replace(p){r,e}      Apply regex replacement to pattern part p
 %highlight(%msg)      ANSI colored message (useful on console)
      Example: 
       "%date{HH:mm:ss} %-5level %-6logger{0} %class{1}.%method:%line - %msg%n"
   → 12:34:56 INFO  http   HttpHandler.handle:42 - GET /users -> 200
      Parameters:
      category - the log category
      pattern - the new pattern

    • setPatternAll

      public static void setPatternAll(String pattern)
      Set the pattern for a all log categories. 
       %date{HH:mm:ss.SSS}   Timestamp (default format shown; many options like ISO8601)
 %level / %-5level     Log level (pad to fixed width with %-5level)
 %logger / %logger{0}  Logger name (full or last component only; {n} = # of segments)
 %thread               Thread name
 %msg / %message       The actual log message
 %n                    Platform-specific newline
 %class / %class{1}    Calling class (full or just last segment with {1})
 %method               Calling method
 %line                 Source line number
 %file                 Source file name
 %caller               Shortcut for class, method, file, and line in one
 %marker               SLF4J marker (if present)
 %X{key}               MDC value for given key
 %replace(p){r,e}      Apply regex replacement to pattern part p
 %highlight(%msg)      ANSI colored message (useful on console)
      Example: 
       "%date{HH:mm:ss} %-5level %-6logger{0} %class{1}.%method:%line - %msg%n"
   → 12:34:56 INFO  http   HttpHandler.handle:42 - GET /users -> 200
      Parameters:
      pattern - the new pattern

    • getPattern

      public static String getPattern(LogCategory category)
      Return the pattern for a log category.
      Parameters:
      category - the log category
      Returns:
      the pattern for the given category

    • addAppender

      public static void addAppender(String id, CategoryLogger.CategoryAppenderFactory factory)
      Register a global appender factory. A separate Appender instance will be created for each registered category.
      Parameters:
      id - the id to register the appender on, so it can be removed later
      factory - the factory that creates the appender with a create(..) method

    • removeAppender

      public static void removeAppender(String id)
      Remove a global appender factory; detaches and stops per-category instances.
      Parameters:
      id - the id the appender was registered with

    • addFormatter

      public static void addFormatter(LogCategory category, String find, Supplier<String> replaceSupplier)
      Add a find-replace formatter on the delegate logger for this category.
      Parameters:
      category - the category to use
      find - the string to find in the pattern
      replaceSupplier - the supplier for the replacement string

    • removeFormatter

      public static void removeFormatter(LogCategory category, String find)
      Remove a find-replace formatter on the delegate logger for this category.
      Parameters:
      category - the category to use
      find - the string to find in the pattern

    • setCallback

      public static void setCallback(LogCategory category, Runnable callback)
      Add a callback method for the delegate logger for this category.
      Parameters:
      category - the category to use
      callback - the runnable that is called just before logging

    • removeCallback

      public static void removeCallback(LogCategory category)
      Remove the callback method for the delegate logger for this category.
      Parameters:
      category - the category to use