Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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` | `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` | `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 java.lang.Throwable` | `getExceptionCause(java.lang.Throwable t)` Returns the exception that caused the given exception, if there is one.
`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.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 void` | `off()` Turns off debugging output except for exception-reporting.
`static void` | `on()` Turns on debugging output.
`static javax.swing.JFrame` | `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(javax.swing.JFrame frame)` Records the GUI frame to use by default when displaying popups.
`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` | `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.

Method Detail

### on

    public static void on()

  Turns on debugging output.

  See Also:
    `off()`

### off

    public static void off()

  Turns off debugging output except for exception-reporting.

  See Also:
    `on()`

### recordMainFrame

    public static void recordMainFrame(javax.swing.JFrame frame)

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

### 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.String message,
                              int i)

### noteln

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

### notelines

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

### 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 javax.swing.JFrame 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.

### getExceptionCause

    public static java.lang.Throwable getExceptionCause(java.lang.Throwable t)

  Returns the exception that caused the given exception, if there is one. Otherwise, return null. This lets us handle exception chains in a reasonably uniform way.

  Starting with Java 1.4, this method can just call the Throwable getCause() method; but we don't take advantage of that, because we still want to be able to use 1.3.

### 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.

### 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 ==.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD