Package org.sosy_lab.common.log

Interface LogManager

  • All Known Implementing Classes:
    BasicLogManager, ForwardingLogManager, LogManagerWithoutDuplicates, NullLogManager, TestLogManager
    public interface LogManager
    Main interface for basic logging framework.

    The log levels used are the ones from java.util.logging. SEVERE, WARNING and INFO are used normally, the first two denoting (among other things) exceptions. FINE, FINER, FINEST, and ALL correspond to main application, central algorithm, component level, and debug level respectively.

    The main advantage of this interface is that the arguments to the log methods are only converted to strings, if the message is really logged.

    • Method Detail

      • withComponentName

        LogManager withComponentName​(String name)
        Returns a new LogManager instance which may use the given name as an indicator from which component a log message comes from.
        Parameters:
        name - A non-empty string.
        Returns:
        A LogManager instance.

      • wouldBeLogged

        boolean wouldBeLogged​(Level priority)
        Returns true if a message with the given log level would be logged.
        Parameters:
        priority - the log level
        Returns:
        whether this log level is enabled

      • log

        void log​(Level priority,
         Object... args)
        Logs any message occurring during program execution. The message is constructed lazily by concatenating the parts with " ". The caller should not use string concatenation to create the message in order to increase performance if the message is never logged. To make individual arguments lazy, use MoreStrings.lazyString(Supplier).
        Parameters:
        priority - the log level for the message
        args - the parts of the message (can be an arbitrary number of objects whose Object.toString() method is called)

      • log

        void log​(Level priority,
         Supplier<String> msgSupplier)
        Logs any message occurring during program execution. The message is constructed lazily by asking the provided supplier if necessary.
        Parameters:
        priority - the log level for the message
        msgSupplier - a supplier for a non-null log message

      • logf

        @FormatMethod
void logf​(Level priority,
          String format,
          Object... args)
        Logs any message occurring during program execution. The message is constructed lazily from String.format(format, args). To make individual arguments lazy, use MoreStrings.lazyString(Supplier).
        Parameters:
        priority - the log level for the message
        format - The format string.
        args - The arguments for the format string.

      • logUserException

        void logUserException​(Level priority,
                      Throwable e,
                      @Nullable String additionalMessage)
        Log a message by printing its message to the user. The details (e.g., stack trace) are hidden from the user and logged with a lower log level.

        Use this method in cases where an expected exception with a useful error message is thrown, e.g. an InvalidConfigurationException.

        If you want to log an IOException because of a write error, it is recommended to write the message like "Could not write FOO to file". The final message will then be "Could not write FOO to file FOO.txt (REASON)".

        Parameters:
        priority - the log level for the message
        e - the occurred exception
        additionalMessage - an optional message

      • logfUserException

        @FormatMethod
void logfUserException​(Level priority,
                       Throwable e,
                       String format,
                       Object... args)
        Log a message by printing its message to the user. The details (e.g., stack trace) are hidden from the user and logged with a lower log level.

        Use this method in cases where an expected exception with a useful error message is thrown, e.g. an InvalidConfigurationException.

        The message is constructed lazily from String.format(format, args). To make individual arguments lazy, use MoreStrings.lazyString(Supplier).

        If you want to log an IOException because of a write error, it is recommended to write the message like "Could not write FOO to file". The final message will then be "Could not write FOO to file FOO.txt (REASON)".

        Parameters:
        priority - the log level for the message
        e - the occurred exception
        format - The format string.
        args - The arguments for the format string.

      • logDebugException

        void logDebugException​(Throwable e,
                       @Nullable String additionalMessage)
        Log an exception solely for the purpose of debugging. In default configuration, this exception is not shown to the user!

        Use this method when you want to log an exception that was handled by the catching site, but you don't want to forget the information completely.

        Parameters:
        e - the occurred exception
        additionalMessage - an optional message

      • logfDebugException

        @FormatMethod
void logfDebugException​(Throwable e,
                        String format,
                        Object... args)
        Log an exception solely for the purpose of debugging. In default configuration, this exception is not shown to the user!

        Use this method when you want to log an exception that was handled by the catching site, but you don't want to forget the information completely.

        The message is constructed lazily from String.format(format, args). To make individual arguments lazy, use MoreStrings.lazyString(Supplier).

        Parameters:
        e - the occurred exception
        format - The format string.
        args - The arguments for the format string.

      • logDebugException

        void logDebugException​(Throwable e)
        Log an exception solely for the purpose of debugging. In default configuration, this exception is not shown to the user!

        Use this method when you want to log an exception that was handled by the catching site, but you don't want to forget the information completely.

        Parameters:
        e - the occurred exception

      • logException

        void logException​(Level priority,
                  Throwable e,
                  @Nullable String additionalMessage)
        Log an exception by printing the full details to the user.

        This method should only be used in cases where logUserException and logDebugException are not acceptable.

        Parameters:
        priority - the log level for the message
        e - the occurred exception
        additionalMessage - an optional message

      • logfException

        @FormatMethod
void logfException​(Level priority,
                   Throwable e,
                   String format,
                   Object... args)
        Log an exception by printing the full details to the user.

        This method should only be used in cases where logUserException and logDebugException are not acceptable.

        The message is constructed lazily from String.format(format, args). To make individual arguments lazy, use MoreStrings.lazyString(Supplier).

        Parameters:
        priority - the log level for the message
        e - the occurred exception
        format - The format string.
        args - The arguments for the format string.

      • flush

        void flush()
        Flush all handlers of this logger.

      • createNullLogManager

        static LogManager createNullLogManager()
        Return a LogManager that does not log anything.

        Note: Do not use this implementation for unit tests, use createTestLogManager() instead.

      • createTestLogManager

        static LogManager createTestLogManager()
        Return a LogManager implementation intended for testing when nothing should actually be logged.

        Compared to createTestLogManager(), it does check all the parameters for validity, i.e. non-nullness and correct string format.