ix.util
Class Debug

java.lang.Object
  ix.util.Debug

public abstract class Debug
extends java.lang.Object

Class for useful static debugging tools

Field Summary

static boolean	noteCaller True iff the "noteln" methods should give the name of the calling class and method at the start of the line.
static boolean	noteThreads True iff the "noteln" methods should give the name of the current thread at the start of the line.
static boolean	on Global on/off control over the debugging output produced by the note and noteln methods.
static java.io.PrintStream	out The output destination used by note and noteln.

Method Summary

static java.lang.String	defaultDescribeException(java.lang.Throwable t)
static java.lang.String	describeException(java.lang.Throwable t) Returns a relatively readable description of an exception.
static void	displayException(java.lang.String preMessage, java.lang.Throwable except) Puts up a description of the exception in a message dialog, making sure that this happens in the AWT event thread.
static void	displayException(java.lang.Throwable except) Calls displayException(String, Throwable) with a null pre-message.
static void	error(java.lang.String message) Deprecated. As of I-X 4.0, just throw instead.
static void	expect(boolean cond) expect checks a condition that should always be true and throws an AssertionFailure if it is not.
static void	expect(boolean cond, java.lang.String message) A variant that allows a message that describes the assertion.
static void	expect(boolean cond, java.lang.String message, java.lang.Object item) A variant that allows a message that describes the assertion plus an Object that the message is about.
static void	expectEquals(java.lang.Object expected, java.lang.Object found) Tests whether an object equals the expected value.
static void	expectEquals(java.lang.Object expected, java.lang.Object found, java.lang.String messagePrefix) Tests whether an object equals the expected value.
static void	expectSame(java.lang.Object expected, java.lang.Object found) Tests whether an object is == to the expected value.
static void	expectSame(java.lang.Object expected, java.lang.Object found, java.lang.String messagePrefix) Tests whether an object is == to the expected value.
static java.lang.String	foldException(java.lang.Throwable t) Calls describeException(Throwable) then breaks the result into lines if it would otherwise be too long.
static void	forceln(java.lang.String message) Produces output even when debug output is off.
static boolean	isOn() Returns true if debugging is on and false otherwise.
static void	note(java.lang.String message) note writes a string to Debug.out if Debug.on is true.
static void	noteElements(java.util.Enumeration e, java.lang.String prefix) Prints the elements of an enumeration on separate lines with a specified prefix at the start of each line.
static void	noteEnumeration(java.util.Enumeration e) Numbers and prints the elements of an Enumeration on separate lines.
static void	noteEnumerationClasses(java.util.Enumeration e) Prints the elements of an Enumeration on separate lines, with an index number and and class name at the start of each line.
static void	noteException(java.lang.Throwable e) Note an exception or error, together with a backtrace.
static void	noteException(java.lang.Throwable e, boolean backtrace) Note an exception or error, optionally with a backtrace.
static void	notelines(java.lang.String[] lines)
static void	noteln(java.lang.Object part1, java.lang.Object part2)
static void	noteln(java.lang.String message) noteln writes a string, followed by a newline, to Debug.out if Debug.on is true.
static void	noteln(java.lang.String message, boolean b)
static void	noteln(java.lang.String message, int i)
static void	noteln(java.lang.String message, java.lang.Object whatever)
static boolean	off() Turns off debugging output except for exception-reporting.
static boolean	on() Turns on debugging output.
static java.awt.Component	probableMainFrame() Returns the frame that is likely to be the agent's main GUI frame.
static void	processParameter(java.lang.String pname, java.lang.String value) Observes parameters as they're set and implements their effects (if any) on debugging output.
static void	recordMainFrame(java.awt.Component frame) Records the GUI frame to use by default when displaying popups.
static boolean	setDebug(boolean v) Turns off debugging output on or off.
static void	setExceptionDescriber(Fn1<java.lang.Throwable,java.lang.String> d)
static void	setNoteFile(java.lang.String filename) Sets the output destination for debugging notes.
static void	setNoteStream(java.io.PrintStream s) Sets the output destination for debugging notes.
static void	showListDifferences(java.util.List l1, java.util.List l2) Describes differences to Debug.out, showing element classes when elements are different.
static void	warn(java.lang.String message) Use this to tell the user about minor problems.

Methods inherited from class java.lang.Object

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

Field Detail

on

public static boolean on

Global on/off control over the debugging output produced by the note and noteln methods. Initially true.

out

public static java.io.PrintStream out

The output destination used by note and noteln. Do not assign directly to this variable. Call setNoteStream or setNoteFile instead. The initial value is System.out.

noteThreads

public static boolean noteThreads

True iff the "noteln" methods should give the name of the current thread at the start of the line. Initially false.

noteCaller

public static boolean noteCaller

True iff the "noteln" methods should give the name of the calling class and method at the start of the line. Initially false.

Method Detail

on

public static boolean on()

Turns on debugging output.

Returns:

the previous value.

See Also:

off()

off

public static boolean off()

Turns off debugging output except for exception-reporting.

Returns:

the previous value.

See Also:

on()

isOn

public static boolean isOn()

Returns true if debugging is on and false otherwise.

setDebug

public static boolean setDebug(boolean v)

Turns off debugging output on or off.

Returns:

the previous value.

See Also:

on(), off()

recordMainFrame

public static void recordMainFrame(java.awt.Component frame)

Records the GUI frame to use by default when displaying popups. This frame will be returned by probableMainFrame().

setExceptionDescriber

public static void setExceptionDescriber(Fn1<java.lang.Throwable,java.lang.String> d)

processParameter

public static void processParameter(java.lang.String pname,
                                    java.lang.String value)

Observes parameters as they're set and implements their effects (if any) on debugging output.

See Also:

Parameters.setParameter(String pname, String value)

note

public static void note(java.lang.String message)

note writes a string to Debug.out if Debug.on is true. It is intetended to replace System.out.print calls, for debugging output.

Unlike noteln, note does not print a newline after the message and does not have variants that take different arguments. The typical use of note is to use several calls to write a line of output. One potential problem with using note is that a different thread may print some other output between those calls.

noteln

public static void noteln(java.lang.String message)

noteln writes a string, followed by a newline, to Debug.out if Debug.on is true. It is intended to replace System.out.println calls, for debugging output. noteln has variants that take more than one argument. The arguments will be printed as strings with single spaces between. The aim here is to avoid string concatenation in the calls to noteln, so that the concatenation will not occur when debugging output is turned off.

noteln

public static void noteln(java.lang.String message,
                          java.lang.Object whatever)

noteln

public static void noteln(java.lang.Object part1,
                          java.lang.Object part2)

noteln

public static void noteln(java.lang.String message,
                          int i)

noteln

public static void noteln(java.lang.String message,
                          boolean b)

notelines

public static void notelines(java.lang.String[] lines)

forceln

public static void forceln(java.lang.String message)

Produces output even when debug output is off.

setNoteStream

public static void setNoteStream(java.io.PrintStream s)

Sets the output destination for debugging notes.

setNoteFile

public static void setNoteFile(java.lang.String filename)

Sets the output destination for debugging notes.

noteException

public static void noteException(java.lang.Throwable e)

Note an exception or error, together with a backtrace. The note is always printed to System.out or System.err, in addition to Debug.out, even when debug output has been turned off or redirected to a file.

noteException

public static void noteException(java.lang.Throwable e,
                                 boolean backtrace)

Note an exception or error, optionally with a backtrace. The note is always printed to System.out or System.err, in addition to Debug.out, even when debug output has been turned off or redirected to a file.

displayException

public static void displayException(java.lang.Throwable except)

Calls displayException(String, Throwable) with a null pre-message.

displayException

public static void displayException(java.lang.String preMessage,
                                    java.lang.Throwable except)

Puts up a description of the exception in a message dialog, making sure that this happens in the AWT event thread. If the call is not already in the event thread, it is moved to it by calling SwingUtilities.invokeAndWait.

The pre-message, if not null, is prefixed to a description of the exception, with ": " as a separator.

Calls noteException(Throwable) first (and before any thread change) so you don't have to. That ensures that a backtrace is printed.

If Parameters.isInteractive() returns false, none of the above applies, and the method simply calls noteException(Throwable).

See Also:

describeException(Throwable)

probableMainFrame

public static java.awt.Component probableMainFrame()

Returns the frame that is likely to be the agent's main GUI frame.

See Also:

#recordMainFrame(JFrame)

describeException

public static java.lang.String describeException(java.lang.Throwable t)

Returns a relatively readable description of an exception. Since an error or exception's message is not always sufficiently meaningful on its own, it is prefixed by the class name (minus the package name). If the exception is an InvocationTargetException, a description of its target exception is included.

defaultDescribeException

public static java.lang.String defaultDescribeException(java.lang.Throwable t)

foldException

public static java.lang.String foldException(java.lang.Throwable t)

Calls describeException(Throwable) then breaks the result into lines if it would otherwise be too long.

See Also:

Strings.foldLongLine(String)

warn

public static void warn(java.lang.String message)

Use this to tell the user about minor problems. Warn prints a message to System.err, followed by a backtrace for the current thread, and also displays the message in a dialog. If method Parameters.isInteractive() returns false, the dialog does not occur and instead a RuntimeException is thrown.

error

public static void error(java.lang.String message)

Deprecated. As of I-X 4.0, just throw instead.

Use this to tell the user about problems that should not be ignored and are not handled locally.

Throws:

java.lang.RuntimeException - as notification of the problem.

noteEnumeration

public static void noteEnumeration(java.util.Enumeration e)

Numbers and prints the elements of an Enumeration on separate lines.

noteEnumerationClasses

public static void noteEnumerationClasses(java.util.Enumeration e)

Prints the elements of an Enumeration on separate lines, with an index number and and class name at the start of each line.

showListDifferences

public static void showListDifferences(java.util.List l1,
                                       java.util.List l2)

Describes differences to Debug.out, showing element classes when elements are different.

noteElements

public static void noteElements(java.util.Enumeration e,
                                java.lang.String prefix)

Prints the elements of an enumeration on separate lines with a specified prefix at the start of each line.

expect

public static void expect(boolean cond)

expect checks a condition that should always be true and throws an AssertionFailure if it is not. expect was originally called "assert", but "assert" became a keyword in Java 1.4.

An assertion is typically used when all of the following apply: the subsequent code requires a condition to be true; in the absence of bugs, the condition always will be true at that point; and it is not obvious that the condition will be true.

AssertionFailure is a RuntimeException and so does not need to be listed in the "throws" clauses of method definitions. One reason for that is to avoid discouraging the use of assertions. If AssertionFailure had to be declared, then adding an assertion in a method that had none before would require nonlocal changes in the code.

Throws:

AssertionFailure - as notification of the problem

See Also:

AssertionFailure

expect

public static void expect(boolean cond,
                          java.lang.String message)

A variant that allows a message that describes the assertion. The message will be printed when the assertion fails and will be included in the AssertionFailure exception.

expect

public static void expect(boolean cond,
                          java.lang.String message,
                          java.lang.Object item)

A variant that allows a message that describes the assertion plus an Object that the message is about.

expectEquals

public static void expectEquals(java.lang.Object expected,
                                java.lang.Object found)

Tests whether an object equals the expected value. By convention, the first argument is the expected value, and the second is the value actually obtained.

Throws:

AssertionFailure - if the objects aren't equal.

expectEquals

public static void expectEquals(java.lang.Object expected,
                                java.lang.Object found,
                                java.lang.String messagePrefix)

Tests whether an object equals the expected value. By convention, the first argument is the expected value, and the second is the value actually obtained.

Throws:

AssertionFailure - if the objects aren't equal.

expectSame

public static void expectSame(java.lang.Object expected,
                              java.lang.Object found)

Tests whether an object is == to the expected value. By convention, the first argument is the expected value, and the second is the value actually obtained.

Throws:

AssertionFailure - if the objects aren't ==.

expectSame

public static void expectSame(java.lang.Object expected,
                              java.lang.Object found,
                              java.lang.String messagePrefix)

Tests whether an object is == to the expected value. By convention, the first argument is the expected value, and the second is the value actually obtained.

Throws:

AssertionFailure - if the objects aren't ==.