public class Debug extends java.lang.Object implements DebugConstants
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 programlog()
-- logging messagesinternal format
escapes.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);
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.
|
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 and Description |
---|
Debug() |
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.
|
public static void addModeChangeListener(@NotNull Debug.ModeChangeListener listener)
listener
- the listener to addpublic static void removeModeChangeListener(@NotNull Debug.ModeChangeListener listener)
listener
- the listener to removepublic static void addTraceMessageDebugListener(@NotNull TraceMessageDebugListener listener)
trace
.listener
- new listenerpublic static void removeTraceMessageDebugListener(@NotNull TraceMessageDebugListener listener)
listener
- listener to removepublic static void addStandardMessageDebugListener(@NotNull StandardMessageDebugListener listener)
message
.listener
- new listenerpublic static void removeStandardMessageDebugListener(@NotNull StandardMessageDebugListener listener)
listener
- listener to removepublic static void addWarningMessageDebugListener(@NotNull WarningMessageDebugListener listener)
warn
.listener
- new listenerpublic static void removeWarningMessageDebugListener(@NotNull WarningMessageDebugListener listener)
listener
- listener to removepublic static void addErrorMessageDebugListener(@NotNull ErrorMessageDebugListener listener)
error
.listener
- new listenerpublic static void removeErrorMessageDebugListener(@NotNull ErrorMessageDebugListener listener)
listener
- listener to removepublic static void addFatalMessageDebugListener(@NotNull FatalMessageDebugListener listener)
fatal
.listener
- new listenerpublic static void removeFatalMessageDebugListener(@NotNull FatalMessageDebugListener listener)
listener
- listener to removepublic static void addAssertionMessageDebugListener(@NotNull AssertionMessageDebugListener listener)
listener
- new listenerpublic static void removeAssertionMessageDebugListener(@NotNull AssertionMessageDebugListener listener)
listener
- listener to removepublic static void addLogMessageListener(@NotNull LogMessageListener listener)
log
.listener
- new listenerpublic static void removeLogMessageListener(@NotNull LogMessageListener listener)
listener
- listener to removepublic static void addCookedMessageDebugListener(@NotNull CookedMessageDebugListener listener)
listener
- new listenerpublic static void removeCookedMessageDebugListener(@NotNull CookedMessageDebugListener listener)
listener
- listener to removepublic static void addAnyMessageDebugListener(@NotNull AnyMessageDebugListener listener)
listener
- new listenerpublic static void removeAnyMessageDebugListener(@NotNull AnyMessageDebugListener listener)
listener
- listener to removepublic static void setMask(long mask)
mask
- debug mask. The possible values are defined in DebugConstants.public static long getMask()
public static void setTraceMode(boolean mode)
mode
- true
= trace messages are handledfalse
= trace messages are discardedpublic static boolean getTraceMode()
true
= trace messages are handledfalse
= trace messages are discardedpublic static void setStandardMode(boolean mode)
mode
- true
= standard messages are handledfalse
= standard messages are discardedpublic static boolean getStandardMode()
true
= standard messages are handledfalse
= standard messages are discardedpublic static void setWarningMode(boolean mode)
mode
- true
= warning messages are handledfalse
= warning messages are discardedpublic static boolean getWarningMode()
true
= warning messages are handledfalse
= warning messages are discardedpublic static void setErrorMode(boolean mode)
mode
- true
= error messages are handledfalse
= error messages are discardedpublic static boolean getErrorMode()
true
= error messages are handledfalse
= error messages are discardedpublic static void setLogMode(boolean mode)
mode
- true
= logging messages are handledfalse
= logging messages are discardedpublic static boolean getLogMode()
true
= logging messages are handledfalse
= logging messages are discardedpublic static void setFatalMode(boolean mode)
mode
- true
= fatal error messages are handledfalse
= fatal error messages are discarded (i.e. no exit)public static boolean getFatalMode()
true
= fatal error messages are handledfalse
= fatal error messages are discarded (i.e. no exit)public static void setAssertionMode(boolean mode)
mode
- true
= assertions are handledfalse
= assertions are discarded (i.e. no Exception)public static boolean getAssertionMode()
true
= assertions are handledfalse
= assertions are discarded (i.e. no Exception)@NotNull public static java.lang.String getStackDump(@NotNull java.lang.Throwable x)
x
- the ThrowablegetErrorMessage(Throwable)
@NotNull public static java.lang.String getErrorMessage(@NotNull java.lang.Throwable x)
x
- exceptiongetStackDump(Throwable)
public static void trace(@NotNull java.lang.String msg)
msg
- messagepublic static void trace(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void trace(@NotNull java.lang.Object obj)
obj
- Objektpublic static void trace(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void tracef(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void message(@NotNull java.lang.String msg)
msg
- messagepublic static void message(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void message(@Nullable java.lang.Object obj)
obj
- objectpublic static void message(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void messagef(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void warn(@NotNull java.lang.String msg)
msg
- messagepublic static void warn(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void warn(@Nullable java.lang.Object obj)
obj
- messagepublic static void warn(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void warnf(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void error(@NotNull java.lang.String msg)
msg
- messagepublic static void error(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void error(@Nullable java.lang.Object obj)
obj
- objektpublic static void error(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void errorf(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void fatal(@NotNull java.lang.String msg)
msg
- messagepublic static void fatal(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void fatal(@Nullable java.lang.Object obj)
obj
- objectpublic static void fatal(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void fatalf(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void log(@NotNull java.lang.String msg)
msg
- messagepublic static void log(@NotNull java.lang.Throwable x)
x
- throwable argumentpublic static void log(@Nullable java.lang.Object obj)
obj
- objectpublic static void log(@NotNull java.lang.String msg, java.lang.Object... args)
msg
- formatted message as defined by Format.format(Object, Object...)
args
- arguments for the formatted messagepublic static void logf(@NotNull java.lang.String format, java.lang.Object... args)
String.format(String, Object...)
.format
- format specifierargs
- further argumentspublic static void insist(boolean condition)
condition
- if false
the assertion has failed and the
listeners are informed with a null messageAssertionFailedError
public static void insist(boolean condition, @NotNull java.lang.String msg)
condition
- if false
the assertion has failed and the
listeners are informedmsg
- the message to send to the listeners on failuresAssertionFailedError
@NotNull public static javax.swing.JFrame createDebugWindow()
@NotNull public static javax.swing.JFrame createDebugWindow(boolean exitOnClose)
exitOnClose
- call System.exit()
when window is closing?static void writeStdoutMessage(@NotNull java.lang.String str)
str
- string written to stdoutstatic void writeStderrMessage(@NotNull java.lang.String str)
str
- string written to stderrpublic static void setStdoutCaptureMode(boolean capture)
capture
- true
= messages are capturedfalse
= message are handled normallypublic static boolean getStdoutCaptureMode()
true
= stdout is capturedfalse
= stdout is handled normallypublic static java.io.PrintStream getConsoleStdout()
public static void setStderrCaptureMode(boolean capture)
capture
- true
= messages are capturedfalse
= message are handled normallypublic static boolean getStderrCaptureMode()
true
= stderr is capturedfalse
= stderr is handled normallypublic static java.io.PrintStream getConsoleStderr()
public static void installCookedOutput(@Nullable java.io.OutputStream stream)
stream
- output streampublic static void installCookedOutput()
public static java.lang.String getObjectInfo(@NotNull java.lang.Object obj)
obj
- object to describeobj
public static java.lang.String getObjectInfoIncludingGetters(@NotNull java.lang.Object obj)
obj
- object to describeobj
public static void initFromProperties(long debugMaskDefault, boolean showWindowDefault, boolean printConsoleDefault)
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:
|
debugMaskDefault
- default mask used if property debug.mask
is not setshowWindowDefault
- default used if property debug.show.window
is not setprintConsoleDefault
- default used if property debug.print.console
is not setpublic static void initFromProperties(long debugMaskDefault)
initFromProperties(long, boolean, boolean)
with no debug window
and no console output as default.debugMaskDefault
- compare initFromProperties(long, boolean, boolean)
public static java.util.logging.Logger connectToLogging()
Even if this method is called more than once, only one connector is created.