de.caff.util.debug

## Class Debug

- java.lang.Object
- - de.caff.util.debug.Debug

- All Implemented Interfaces:
    DebugConstants

      public class Debug
      extends java.lang.Object
      implements DebugConstants

  General tool for debugging purposes.

  This class defines static methods allowing output of debugging messages and assertion checks.

  Debugging messages fall into 6 categories handled by appropriately named methods.

  - `trace()` -- trace messages (ultra low level priority)
  - `message()` -- standard messages (low level priority)
  - `warn()` -- warning messages (normal priority)
  - `error()` -- error messages (high priority)
  - `fatal()` -- fatal error messages (ultra high priority), allowing to interrupt program
  - `log()` -- logging messages
  Each of these methods is overloaded to accept
  - a String parameter
  - an Exception parameter
  - a format parameter and possible argument using `internal format` escapes.
  There are also variants where a `f` character is appended to the name (eg. `tracef()` or `logf()`) which use standard `String.format()` format. It is possible to set the locale for this formatting via Java property `debug.locale` (evaluated when this class is initialized).

  There is an `insist()` (formerly called `assert` until it became a Java keyword) method allowing to define assertions, too.

  Each of the 6 categories and the handling of assertions can be switched on or off globally. Switching a category off means that debug messages in that category are not captured but discarded. Discarding is done as early as possible so there is only a small overhead with discarded messages (a method call, possibly parameter boxing, one if). Capturing a lot of messages may slow down a program considerably (here a lot depends on the registered listeners).

  For every category there's a dedicated listener interface allowing listeners to register for that kind of messages (including an `AnyMessageDebugListener` interface for registration on all categories). These listeners will receive raw messages, i.e. get directly the messages as they are sent in the code. There's another `CookedMessageDebugListener` interface where listeners receive cooked messages. Cooked messages include the time and the sender's file position as well as an indicator of the category of the message.

  There are no listeners registered by default but there are convenience methods allowing to create a simple listener allowing output on stdout (see `installCookedOutput()`) or a stream (see `installCookedOutput(java.io.OutputStream)`) and a method which creates a JFrame to display the messages and allowing switching of the categories (see `createDebugWindow()` or `createDebugWindow(boolean)`).

  It's possible to capture the standard output streams of the program. When this is done text printed to `stdout` is send via the `message()` interface and text printed to `stderr` is send via the `error()` interface. When captured these streams are buffered until another kind of message arrives or capturing is switched off.

  You should prefer the following syntax when writing debug messages

          Debug.trace("foo=%1", foo);

  instead of

          Debug.trace("foo="+foo);

  Author:
    Rammi
  See Also:
    `Format`, `AnyMessageDebugListener`, `AssertionMessageDebugListener`, `CookedMessageDebugListener`, `ErrorMessageDebugListener`, `FatalMessageDebugListener`, `LogMessageListener`, `StandardMessageDebugListener`, `WarningMessageDebugListener`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Debug.ModeChangeListener` A Java interface for listeners which wants to be informed about the internal mode of the debug interface.

  - ### Field Summary

    - ### Fields inherited from interface de.caff.util.debug.DebugConstants

      `ASSERT, ASSERT_CHAR, ASSERT_FLAG, DEBUG_ALL_MASK, ERROR, ERROR_CHAR, ERROR_FLAG, FATAL, FATAL_CHAR, FATAL_FLAG, LOG, LOG_CHAR, LOG_FLAG, MESSAGE, MESSAGE_CHAR, MESSAGE_FLAG, NO_DEBUG_MASK, NR_DEBUG_TYPES, TRACE, TRACE_CHAR, TRACE_FLAG, WARNING, WARNING_CHAR, WARNING_FLAG`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Debug()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addAnyMessageDebugListener(AnyMessageDebugListener listener)` Append a listener for all messages.
    `static void` | `addAssertionMessageDebugListener(AssertionMessageDebugListener listener)` Add an assert message debug listener.
    `static void` | `addCookedMessageDebugListener(CookedMessageDebugListener listener)` Append a listener for cooked messages.
    `static void` | `addErrorMessageDebugListener(ErrorMessageDebugListener listener)` Append an error message debug listener.
    `static void` | `addFatalMessageDebugListener(FatalMessageDebugListener listener)` Append a fatal error message debug listener.
    `static void` | `addLogMessageListener(LogMessageListener listener)` Append a log message listener.
    `static void` | `addModeChangeListener(Debug.ModeChangeListener listener)` Add a ModeChangeListener.
    `static void` | `addStandardMessageDebugListener(StandardMessageDebugListener listener)` Append a standard debug message listener.
    `static void` | `addTraceMessageDebugListener(TraceMessageDebugListener listener)` Append a trace message listener.
    `static void` | `addWarningMessageDebugListener(WarningMessageDebugListener listener)` Append a warning message debug listener.
    `static java.util.logging.Logger` | `connectToLogging()` Connect this debugger to the standard Java logging system located in package java.util.debug and introduced in Java 1.4.
    `static javax.swing.JFrame` | `createDebugWindow()` Create a debug window which receives cooked messages.
    `static javax.swing.JFrame` | `createDebugWindow(boolean exitOnClose)` Create a debug window which receives cooked messages.
    `static void` | `error(java.lang.Object obj)` Print an error message without further arguments.
    `static void` | `error(java.lang.String msg)` Print an error message without further arguments.
    `static void` | `error(java.lang.String msg, java.lang.Object... args)` Print an error message with up to nine arguments.
    `static void` | `error(java.lang.Throwable x)` Print an error message for a throwable.
    `static void` | `errorf(java.lang.String format, java.lang.Object... args)` Print a trace message in the format used by `String.format(String, Object...)`.
    `static void` | `fatal(java.lang.Object obj)` Print a fatal error message without further arguments.
    `static void` | `fatal(java.lang.String msg)` Print a fatal error message without further arguments.
    `static void` | `fatal(java.lang.String msg, java.lang.Object... args)` Print a fatal error message with up to nine arguments.
    `static void` | `fatal(java.lang.Throwable x)` Print a fatal error message for a throwable.
    `static void` | `fatalf(java.lang.String format, java.lang.Object... args)` Print a trace message in the format used by `String.format(String, Object...)`.
    `static boolean` | `getAssertionMode()` Get the assertion handling mode.
    `static java.io.PrintStream` | `getConsoleStderr()` Get the stderr stream which prints to the console.
    `static java.io.PrintStream` | `getConsoleStdout()` Get the stdout stream which prints to the console.
    `static java.lang.String` | `getErrorMessage(java.lang.Throwable x)` Get a (halfways) useful message from an exception.
    `static boolean` | `getErrorMode()` Set the error message mode.
    `static boolean` | `getFatalMode()` Get the fatal error message mode.
    `static boolean` | `getLogMode()` Get the logging message mode.
    `static long` | `getMask()` Get the active debugging mask.
    `static java.lang.String` | `getObjectInfo(java.lang.Object obj)` Create an in-deep description of the fields of the given object.
    `static java.lang.String` | `getObjectInfoIncludingGetters(java.lang.Object obj)` Create an in-deep description of the fields and the getter methods of the given object.
    `static java.lang.String` | `getStackDump(java.lang.Throwable x)` Create a stack dump from a Throwable.
    `static boolean` | `getStandardMode()` Get the standard message mode.
    `static boolean` | `getStderrCaptureMode()` Get the actual capturing mode for stderr.
    `static boolean` | `getStdoutCaptureMode()` Get the actual capturing mode for stdout.
    `static boolean` | `getTraceMode()` Get the trace mode.
    `static boolean` | `getWarningMode()` Get the warning message mode.
    `static void` | `initFromProperties(long debugMaskDefault)` Convenience method which calls `initFromProperties(long, boolean, boolean)` with no debug window and no console output as default.
    `static void` | `initFromProperties(long debugMaskDefault, boolean showWindowDefault, boolean printConsoleDefault)` Initialize debugging features from properties.
    `static void` | `insist(boolean condition)` Test an assertion.
    `static void` | `insist(boolean condition, java.lang.String msg)` Test an assertion.
    `static void` | `installCookedOutput()` Install a DebugListener which prints all messages in "cooked" form to the console.
    `static void` | `installCookedOutput(java.io.OutputStream stream)` Install a DebugListener which prints all messages in "cooked" form to the given output stream.
    `static void` | `log(java.lang.Object obj)` Print a logging message without further arguments.
    `static void` | `log(java.lang.String msg)` Print a logging message without further arguments.
    `static void` | `log(java.lang.String msg, java.lang.Object... args)` Print a logging message with up to nine arguments.
    `static void` | `log(java.lang.Throwable x)` Print a logging message for a throwable.
    `static void` | `logf(java.lang.String format, java.lang.Object... args)` Print a logging message in the format used by `String.format(String, Object...)`.
    `static void` | `message(java.lang.Object obj)` Print a standard message without further arguments.
    `static void` | `message(java.lang.String msg)` Print a standard message without further arguments.
    `static void` | `message(java.lang.String msg, java.lang.Object... args)` Print a standard message with up to nine arguments.
    `static void` | `message(java.lang.Throwable x)` Print a standard message from a throwable.
    `static void` | `messagef(java.lang.String format, java.lang.Object... args)` Print a trace message in the format used by `String.format(String, Object...)`.
    `static void` | `removeAnyMessageDebugListener(AnyMessageDebugListener listener)` Remove a listener for all messages.
    `static void` | `removeAssertionMessageDebugListener(AssertionMessageDebugListener listener)` Remove an assert message debug listener.
    `static void` | `removeCookedMessageDebugListener(CookedMessageDebugListener listener)` Remove a listener for cooked messages.
    `static void` | `removeErrorMessageDebugListener(ErrorMessageDebugListener listener)` Remove an error message debug listener.
    `static void` | `removeFatalMessageDebugListener(FatalMessageDebugListener listener)` Remove a fatal error message debug listener.
    `static void` | `removeLogMessageListener(LogMessageListener listener)` Remove a log message listener.
    `static void` | `removeModeChangeListener(Debug.ModeChangeListener listener)` Remove a mode change listener
    `static void` | `removeStandardMessageDebugListener(StandardMessageDebugListener listener)` Remove a standard debug message listener.
    `static void` | `removeTraceMessageDebugListener(TraceMessageDebugListener listener)` Remove a trace message listener
    `static void` | `removeWarningMessageDebugListener(WarningMessageDebugListener listener)` Remove a warning message debug listener.
    `static void` | `setAssertionMode(boolean mode)` Set the assertion handling mode.
    `static void` | `setErrorMode(boolean mode)` Set the error message mode.
    `static void` | `setFatalMode(boolean mode)` Set the fatal error message mode.
    `static void` | `setLogMode(boolean mode)` Set the logging message mode.
    `static void` | `setMask(long mask)` Set the debugging mask.
    `static void` | `setStandardMode(boolean mode)` Set the standard message mode.
    `static void` | `setStderrCaptureMode(boolean capture)` How messages to stderr shall be handled.
    `static void` | `setStdoutCaptureMode(boolean capture)` How messages to stdout shall be handled.
    `static void` | `setTraceMode(boolean mode)` Set the trace mode.
    `static void` | `setWarningMode(boolean mode)` Set the warning message mode.
    `static void` | `trace(java.lang.Object obj)` Print a trace message without further arguments.
    `static void` | `trace(java.lang.String msg)` Print a trace message without further arguments.
    `static void` | `trace(java.lang.String msg, java.lang.Object... args)` Print a trace message with up to nine arguments.
    `static void` | `trace(java.lang.Throwable x)` Print a trace message from a throwable.
    `static void` | `tracef(java.lang.String format, java.lang.Object... args)` Print a trace message in the format used by `String.format(String, Object...)`.
    `static void` | `warn(java.lang.Object obj)` Print a warning message without further arguments.
    `static void` | `warn(java.lang.String msg)` Print a warning message without further arguments.
    `static void` | `warn(java.lang.String msg, java.lang.Object... args)` Print a warning message with up to nine arguments.
    `static void` | `warn(java.lang.Throwable x)` Print warning message from a throwable.
    `static void` | `warnf(java.lang.String format, java.lang.Object... args)` Print a trace message in the format used by `String.format(String, Object...)`.
    `(package private) static void` | `writeStderrMessage(java.lang.String str)` Handle a message to stderr.
    `(package private) static void` | `writeStdoutMessage(java.lang.String str)` Handle a message to stdout.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Debug

          public Debug()

  - ### Method Detail

    - #### addModeChangeListener

          public static void addModeChangeListener(@NotNull
                                                   Debug.ModeChangeListener listener)

      Add a ModeChangeListener.
      Parameters:
        `listener` - the listener to add

    - #### removeModeChangeListener

          public static void removeModeChangeListener(@NotNull
                                                      Debug.ModeChangeListener listener)

      Remove a mode change listener
      Parameters:
        `listener` - the listener to remove

    - #### addTraceMessageDebugListener

          public static void addTraceMessageDebugListener(@NotNull
                                                          TraceMessageDebugListener listener)

      Append a trace message listener. This listener will receive debug messages sent with `trace`.
      Parameters:
        `listener` - new listener

    - #### removeTraceMessageDebugListener

          public static void removeTraceMessageDebugListener(@NotNull
                                                             TraceMessageDebugListener listener)

      Remove a trace message listener
      Parameters:
        `listener` - listener to remove

    - #### addStandardMessageDebugListener

          public static void addStandardMessageDebugListener(@NotNull
                                                             StandardMessageDebugListener listener)

      Append a standard debug message listener. This listener will receive debug messages sent with `message`.
      Parameters:
        `listener` - new listener

    - #### removeStandardMessageDebugListener

          public static void removeStandardMessageDebugListener(@NotNull
                                                                StandardMessageDebugListener listener)

      Remove a standard debug message listener.
      Parameters:
        `listener` - listener to remove

    - #### addWarningMessageDebugListener

          public static void addWarningMessageDebugListener(@NotNull
                                                            WarningMessageDebugListener listener)

      Append a warning message debug listener. This listener will receive debug messages sent with `warn`.
      Parameters:
        `listener` - new listener

    - #### removeWarningMessageDebugListener

          public static void removeWarningMessageDebugListener(@NotNull
                                                               WarningMessageDebugListener listener)

      Remove a warning message debug listener.
      Parameters:
        `listener` - listener to remove

    - #### addErrorMessageDebugListener

          public static void addErrorMessageDebugListener(@NotNull
                                                          ErrorMessageDebugListener listener)

      Append an error message debug listener. This listener will receive messages sent with `error`.
      Parameters:
        `listener` - new listener

    - #### removeErrorMessageDebugListener

          public static void removeErrorMessageDebugListener(@NotNull
                                                             ErrorMessageDebugListener listener)

      Remove an error message debug listener.
      Parameters:
        `listener` - listener to remove

    - #### addFatalMessageDebugListener

          public static void addFatalMessageDebugListener(@NotNull
                                                          FatalMessageDebugListener listener)

      Append a fatal error message debug listener. This listener will receive messages sent with `fatal`.
      Parameters:
        `listener` - new listener

    - #### removeFatalMessageDebugListener

          public static void removeFatalMessageDebugListener(@NotNull
                                                             FatalMessageDebugListener listener)

      Remove a fatal error message debug listener.
      Parameters:
        `listener` - listener to remove

    - #### addAssertionMessageDebugListener

          public static void addAssertionMessageDebugListener(@NotNull
                                                              AssertionMessageDebugListener listener)

      Add an assert message debug listener. This listener will receive assert messages on failed assertions and can initiate a exception.
      Parameters:
        `listener` - new listener

    - #### removeAssertionMessageDebugListener

          public static void removeAssertionMessageDebugListener(@NotNull
                                                                 AssertionMessageDebugListener listener)

      Remove an assert message debug listener.
      Parameters:
        `listener` - listener to remove

    - #### addLogMessageListener

          public static void addLogMessageListener(@NotNull
                                                   LogMessageListener listener)

      Append a log message listener. This listener will receive messages sent with `log`.
      Parameters:
        `listener` - new listener

    - #### removeLogMessageListener

          public static void removeLogMessageListener(@NotNull
                                                      LogMessageListener listener)

      Remove a log message listener.
      Parameters:
        `listener` - listener to remove

    - #### addCookedMessageDebugListener

          public static void addCookedMessageDebugListener(@NotNull
                                                           CookedMessageDebugListener listener)

      Append a listener for cooked messages. This listener will receive messages of all allowed categories in an enhanced format.
      Parameters:
        `listener` - new listener

    - #### removeCookedMessageDebugListener

          public static void removeCookedMessageDebugListener(@NotNull
                                                              CookedMessageDebugListener listener)

      Remove a listener for cooked messages.
      Parameters:
        `listener` - listener to remove

    - #### addAnyMessageDebugListener

          public static void addAnyMessageDebugListener(@NotNull
                                                        AnyMessageDebugListener listener)

      Append a listener for all messages. This listener will receive messages of all allowed categories in raw format.
      Parameters:
        `listener` - new listener

    - #### removeAnyMessageDebugListener

          public static void removeAnyMessageDebugListener(@NotNull
                                                           AnyMessageDebugListener listener)

      Remove a listener for all messages.
      Parameters:
        `listener` - listener to remove

    - #### setMask

          public static void setMask(long mask)

      Set the debugging mask. This allows one step setting of which messages are handled or discarded.
      Parameters:
        `mask` - debug mask. The possible values are defined in DebugConstants.

    - #### getMask

          public static long getMask()

      Get the active debugging mask.
      Returns:
        debugging mask. The possible values are defined in DebugConstant.

    - #### setTraceMode

          public static void setTraceMode(boolean mode)

      Set the trace mode.
      Parameters:
        `mode` - `true` = trace messages are handled
        `false` = trace messages are discarded

    - #### getTraceMode

          public static boolean getTraceMode()

      Get the trace mode.
      Returns:
        `true` = trace messages are handled
        `false` = trace messages are discarded

    - #### setStandardMode

          public static void setStandardMode(boolean mode)

      Set the standard message mode.
      Parameters:
        `mode` - `true` = standard messages are handled
        `false` = standard messages are discarded

    - #### getStandardMode

          public static boolean getStandardMode()

      Get the standard message mode.
      Returns:
        `true` = standard messages are handled
        `false` = standard messages are discarded

    - #### setWarningMode

          public static void setWarningMode(boolean mode)

      Set the warning message mode.
      Parameters:
        `mode` - `true` = warning messages are handled
        `false` = warning messages are discarded

    - #### getWarningMode

          public static boolean getWarningMode()

      Get the warning message mode.
      Returns:
        `true` = warning messages are handled
        `false` = warning messages are discarded

    - #### setErrorMode

          public static void setErrorMode(boolean mode)

      Set the error message mode.
      Parameters:
        `mode` - `true` = error messages are handled
        `false` = error messages are discarded

    - #### getErrorMode

          public static boolean getErrorMode()

      Set the error message mode.
      Returns:
        `true` = error messages are handled
        `false` = error messages are discarded

    - #### setLogMode

          public static void setLogMode(boolean mode)

      Set the logging message mode.
      Parameters:
        `mode` - `true` = logging messages are handled
        `false` = logging messages are discarded

    - #### getLogMode

          public static boolean getLogMode()

      Get the logging message mode.
      Returns:
        `true` = logging messages are handled
        `false` = logging messages are discarded

    - #### setFatalMode

          public static void setFatalMode(boolean mode)

      Set the fatal error message mode.
      Parameters:
        `mode` - `true` = fatal error messages are handled
        `false` = fatal error messages are discarded (i.e. no exit)

    - #### getFatalMode

          public static boolean getFatalMode()

      Get the fatal error message mode.
      Returns:
        `true` = fatal error messages are handled
        `false` = fatal error messages are discarded (i.e. no exit)

    - #### setAssertionMode

          public static void setAssertionMode(boolean mode)

      Set the assertion handling mode.
      Parameters:
        `mode` - `true` = assertions are handled
        `false` = assertions are discarded (i.e. no Exception)

    - #### getAssertionMode

          public static boolean getAssertionMode()

      Get the assertion handling mode.
      Returns:
        `true` = assertions are handled
        `false` = assertions are discarded (i.e. no Exception)

    - #### getStackDump

          @NotNull
          public static java.lang.String getStackDump(@NotNull
                                                               java.lang.Throwable x)

      Create a stack dump from a Throwable.
      Parameters:
        `x` - the Throwable
      Returns:
        stack dump
      See Also:
        `getErrorMessage(Throwable)`

    - #### getErrorMessage

          @NotNull
          public static java.lang.String getErrorMessage(@NotNull
                                                                  java.lang.Throwable x)

      Get a (halfways) useful message from an exception.
      Parameters:
        `x` - exception
      Returns:
        error message
      See Also:
        `getStackDump(Throwable)`

    - #### trace

          public static void trace(@NotNull
                                   java.lang.String msg)

      Print a trace message without further arguments.
      Parameters:
        `msg` - message

    - #### trace

          public static void trace(@NotNull
                                   java.lang.Throwable x)

      Print a trace message from a throwable.
      Parameters:
        `x` - throwable argument

    - #### trace

          public static void trace(@NotNull
                                   java.lang.Object obj)

      Print a trace message without further arguments.
      Parameters:
        `obj` - Objekt

    - #### trace

          public static void trace(@NotNull
                                   java.lang.String msg,
                                   java.lang.Object... args)

      Print a trace message with up to nine arguments.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### tracef

          public static void tracef(@NotNull
                                    java.lang.String format,
                                    java.lang.Object... args)

      Print a trace message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### message

          public static void message(@NotNull
                                     java.lang.String msg)

      Print a standard message without further arguments.
      Parameters:
        `msg` - message

    - #### message

          public static void message(@NotNull
                                     java.lang.Throwable x)

      Print a standard message from a throwable.
      Parameters:
        `x` - throwable argument

    - #### message

          public static void message(@Nullable
                                     java.lang.Object obj)

      Print a standard message without further arguments.
      Parameters:
        `obj` - object

    - #### message

          public static void message(@NotNull
                                     java.lang.String msg,
                                     java.lang.Object... args)

      Print a standard message with up to nine arguments.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### messagef

          public static void messagef(@NotNull
                                      java.lang.String format,
                                      java.lang.Object... args)

      Print a trace message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### warn

          public static void warn(@NotNull
                                  java.lang.String msg)

      Print a warning message without further arguments.
      Parameters:
        `msg` - message

    - #### warn

          public static void warn(@NotNull
                                  java.lang.Throwable x)

      Print warning message from a throwable.
      Parameters:
        `x` - throwable argument

    - #### warn

          public static void warn(@Nullable
                                  java.lang.Object obj)

      Print a warning message without further arguments.
      Parameters:
        `obj` - message

    - #### warn

          public static void warn(@NotNull
                                  java.lang.String msg,
                                  java.lang.Object... args)

      Print a warning message with up to nine arguments.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### warnf

          public static void warnf(@NotNull
                                   java.lang.String format,
                                   java.lang.Object... args)

      Print a trace message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### error

          public static void error(@NotNull
                                   java.lang.String msg)

      Print an error message without further arguments.
      Parameters:
        `msg` - message

    - #### error

          public static void error(@NotNull
                                   java.lang.Throwable x)

      Print an error message for a throwable.
      Parameters:
        `x` - throwable argument

    - #### error

          public static void error(@Nullable
                                   java.lang.Object obj)

      Print an error message without further arguments.
      Parameters:
        `obj` - objekt

    - #### error

          public static void error(@NotNull
                                   java.lang.String msg,
                                   java.lang.Object... args)

      Print an error message with up to nine arguments.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### errorf

          public static void errorf(@NotNull
                                    java.lang.String format,
                                    java.lang.Object... args)

      Print a trace message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### fatal

          public static void fatal(@NotNull
                                   java.lang.String msg)

      Print a fatal error message without further arguments. This may end the program if a listener to fatal errors decides to do so.
      Parameters:
        `msg` - message

    - #### fatal

          public static void fatal(@NotNull
                                   java.lang.Throwable x)

      Print a fatal error message for a throwable. This may end the program if a listener to fatal errors decides to do so.
      Parameters:
        `x` - throwable argument

    - #### fatal

          public static void fatal(@Nullable
                                   java.lang.Object obj)

      Print a fatal error message without further arguments. This may end the program if a listener to fatal errors decides to do so.
      Parameters:
        `obj` - object

    - #### fatal

          public static void fatal(@NotNull
                                   java.lang.String msg,
                                   java.lang.Object... args)

      Print a fatal error message with up to nine arguments. This may end the program if a listener to fatal errors decides to do so.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### fatalf

          public static void fatalf(@NotNull
                                    java.lang.String format,
                                    java.lang.Object... args)

      Print a trace message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### log

          public static void log(@NotNull
                                 java.lang.String msg)

      Print a logging message without further arguments.
      Parameters:
        `msg` - message

    - #### log

          public static void log(@NotNull
                                 java.lang.Throwable x)

      Print a logging message for a throwable.
      Parameters:
        `x` - throwable argument

    - #### log

          public static void log(@Nullable
                                 java.lang.Object obj)

      Print a logging message without further arguments.
      Parameters:
        `obj` - object

    - #### log

          public static void log(@NotNull
                                 java.lang.String msg,
                                 java.lang.Object... args)

      Print a logging message with up to nine arguments.
      Parameters:
        `msg` - formatted message as defined by `Format.format(Object, Object...)`
        `args` - arguments for the formatted message

    - #### logf

          public static void logf(@NotNull
                                  java.lang.String format,
                                  java.lang.Object... args)

      Print a logging message in the format used by `String.format(String, Object...)`.
      Parameters:
        `format` - format specifier
        `args` - further arguments

    - #### insist

          public static void insist(boolean condition)

      Test an assertion. Depending on the registered listeners an assertion failure error is thrown.
      Parameters:
        `condition` - if `false` the assertion has failed and the listeners are informed with a null message
      See Also:
        `AssertionFailedError`

    - #### insist

          public static void insist(boolean condition,
                                    @NotNull
                                    java.lang.String msg)

      Test an assertion. Depending on the registered listeners an assertion failure error is thrown.
      Parameters:
        `condition` - if `false` the assertion has failed and the listeners are informed
        `msg` - the message to send to the listeners on failures
      See Also:
        `AssertionFailedError`

    - #### createDebugWindow

          @NotNull
          public static javax.swing.JFrame createDebugWindow()

      Create a debug window which receives cooked messages. It contains some simple buttons allowing to change the categories and the capturing of stdout/stderr globally. This window does not exit when closing.
      Returns:
        win the window

    - #### createDebugWindow

          @NotNull
          public static javax.swing.JFrame createDebugWindow(boolean exitOnClose)

      Create a debug window which receives cooked messages. It contains some simple buttons allowing to change the categories and the capturing of stdout/stderr globally.
      Parameters:
        `exitOnClose` - call `System.exit()` when window is closing?
      Returns:
        win the window

    - #### writeStdoutMessage

          static void writeStdoutMessage(@NotNull
                                         java.lang.String str)

      Handle a message to stdout.
      Parameters:
        `str` - string written to stdout

    - #### writeStderrMessage

          static void writeStderrMessage(@NotNull
                                         java.lang.String str)

      Handle a message to stderr.
      Parameters:
        `str` - string written to stderr

    - #### setStdoutCaptureMode

          public static void setStdoutCaptureMode(boolean capture)

      How messages to stdout shall be handled.
      Parameters:
        `capture` - `true` = messages are captured
        `false` = message are handled normally

    - #### getStdoutCaptureMode

          public static boolean getStdoutCaptureMode()

      Get the actual capturing mode for stdout.
      Returns:
        `true` = stdout is captured
        `false` = stdout is handled normally

    - #### getConsoleStdout

          public static java.io.PrintStream getConsoleStdout()

      Get the stdout stream which prints to the console.
      Returns:
        the real stdout stream

    - #### setStderrCaptureMode

          public static void setStderrCaptureMode(boolean capture)

      How messages to stderr shall be handled.
      Parameters:
        `capture` - `true` = messages are captured
        `false` = message are handled normally

    - #### getStderrCaptureMode

          public static boolean getStderrCaptureMode()

      Get the actual capturing mode for stderr.
      Returns:
        `true` = stderr is captured
        `false` = stderr is handled normally

    - #### getConsoleStderr

          public static java.io.PrintStream getConsoleStderr()

      Get the stderr stream which prints to the console.
      Returns:
        the real stderr stream

    - #### installCookedOutput

          public static void installCookedOutput(@Nullable
                                                 java.io.OutputStream stream)

      Install a DebugListener which prints all messages in "cooked" form to the given output stream.
      Parameters:
        `stream` - output stream

    - #### installCookedOutput

          public static void installCookedOutput()

      Install a DebugListener which prints all messages in "cooked" form to the console.

    - #### getObjectInfo

          public static java.lang.String getObjectInfo(@NotNull
                                                       java.lang.Object obj)

      Create an in-deep description of the fields of the given object.
      Parameters:
        `obj` - object to describe
      Returns:
        description of `obj`

    - #### getObjectInfoIncludingGetters

          public static java.lang.String getObjectInfoIncludingGetters(@NotNull
                                                                       java.lang.Object obj)

      Create an in-deep description of the fields and the getter methods of the given object. Beware that all public non parameter methods starting with `get` will be called if the security manager allows, which might cause side-effects!
      Parameters:
        `obj` - object to describe
      Returns:
        description of `obj`

    - #### initFromProperties

          public static void initFromProperties(long debugMaskDefault,
                                                boolean showWindowDefault,
                                                boolean printConsoleDefault)

      Initialize debugging features from properties. Depending on the settings of certain properties the initial debugging settings are set:

      Property | Type | Description
      --- | --- | ---
      `debug.show.window` | `boolean` | Display a debug window?
      `debug.print.console` | `boolean` | Print debug messages to console/stdout?
      `debug.mask` | `String` | Combination of characters indicating which types of debug messages should be captured:
      Character to Level Mapping
      `T` | Trace messages (lowest priority)
      `S` | Standard messages
      `W` | Warning messages
      `E` | Error messages
      `F` | Fatal error messages (highest priority)
      `L` | Log messages
      `A` | Assertion failure messages

      If neither a debug window is displayed nor something is printed to the console the mask is ignored and no type of message is captured.
      Parameters:
        `debugMaskDefault` - default mask used if property `debug.mask` is not set
        `showWindowDefault` - default used if property `debug.show.window` is not set
        `printConsoleDefault` - default used if property `debug.print.console` is not set

    - #### initFromProperties

          public static void initFromProperties(long debugMaskDefault)

      Convenience method which calls `initFromProperties(long, boolean, boolean)` with no debug window and no console output as default.
      Parameters:
        `debugMaskDefault` - compare `initFromProperties(long, boolean, boolean)`

    - #### connectToLogging

          public static java.util.logging.Logger connectToLogging()

      Connect this debugger to the standard Java logging system located in package java.util.debug and introduced in Java 1.4.

      Even if this method is called more than once, only one connector is created.

      Returns:
        logger connecting the debug system to the logging system