lapisx.util
Class Debug

java.lang.Object
  lapisx.util.Debug

Direct Known Subclasses:

Debug.NoDebug, Debug.Verbose

public abstract class Debug

extends Object

Debugging output that can be enabled and disabled on a per-class basis. Using Debug is a three-step process. First, declare a public static (but not final) variable called debug in your class. Its default value should generally be Debug.QUIET:

   import lapisx.util.Debug;
 
   public class MyClass {
      public static Debug debug = Debug.QUIET;
 

Second, whenever you want to print debugging output, use the debug variable instead of System.out or System.err:

   debug.println ("this is my debugging message"); 
   // instead of System.err.println()
   ...
 
   try {
     ...
   } catch (Exception e) {
     debug.report (e); 
     // instead of e.printStackTrace()
     ...
   }
 
   debug.assertion (obj != null);
   // to check assertions
 

Third, when you run your program, use setDebugLevel(java.lang.Class, lapisx.util.Debug) to enable and disable debugging on a class-by-class basis:

   Debug.setDebugLevel (MyClass.class, Debug.VERBOSE);
 

In LAPIS, you can use the -debug command-line parameter to enable debugging output for the classes you want to debug:

   lapis -debug MyClass,MyOtherClass,...
 

If you have a set of related classes that are always debugged simultaneously, then you may want them to share a single debug variable for convenience.

Nested Class Summary

static class	Debug.NoDebug Debug object that prints nothing and checks no assertions.
static class	Debug.Quiet Debug object that only prints exception stack traces and assertion failures.
static class	Debug.Verbose Debug object that prints all messages, exception stack traces, and checks all assertions.

Field Summary

static Debug	NONE Disables all debugging output and assertion checks.
static Debug	QUIET Enables only exception reports and assertion checks.
static Debug	VERBOSE Enables all debugging output and assertion checks.

Constructor Summary

Debug()

Method Summary

abstract void	assertion(boolean f) Test an assertion (if this is enabled for assertions)
abstract boolean	assertionEnabled() Test whether calling assertion() on this debug object will do anything.
static Debug	getDebugLevel(Class cls) Get the debugging object currently in use by a class.
abstract OutputStream	getOutputStream() Returns the OutputStream associated with this debug object.
abstract void	print(Object obj) Print an object (if this is enabled for printing)
abstract void	print(String message) Print message (if this is enabled for printing)
abstract boolean	printEnabled() Test whether calling print() or println() on this debug object will print anything.
abstract void	println(Object obj) Print an object (if this is enabled for printing)
abstract void	println(String message) Print message (if this is enabled for printing)
abstract void	printStackTrace() Print stack trace of current execution point (if this is enabled for debugging printing)
abstract void	printThreadInfo() Print a list of active threads (if this is enabled for printing)
abstract void	report(Throwable t) Print the stack trace of an exception (if this is enabled for reporting exceptions)
abstract boolean	reportEnabled() Test whether calling report() on this debug object will print anything.
static void	setDebugLevel(Class cls, Debug level) Set the debugging object used by a class.

Methods inherited from class java.lang.Object

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

Field Detail

VERBOSE

public static final Debug VERBOSE

Enables all debugging output and assertion checks. Assertion failures throw a RuntimeException. Output is sent to System.err.

QUIET

public static final Debug QUIET

Enables only exception reports and assertion checks. Disables other printing. Assertion failures print an exception report, but don't throw any exceptions, so computation can proceed. Output is sent to System.err.

NONE

public static final Debug NONE

Disables all debugging output and assertion checks.

Constructor Detail

Debug

public Debug()

Method Detail

getDebugLevel

public static Debug getDebugLevel(Class cls)
                           throws NoSuchFieldException

Get the debugging object currently in use by a class.

Parameters:

cls - Class to query

Returns:

Debug object found in the public static field "debug" of cls.

Throws:

NoSuchFieldException - if cls has no public static field named "debug"

setDebugLevel

public static void setDebugLevel(Class cls,
                                 Debug level)
                          throws NoSuchFieldException

Set the debugging object used by a class. Call this method to enable or disable the class's debugging output, e.g. Debug.setDebugLevel (MyClass.class, Debug.VERBOSE).

Parameters:

cls - Class to modify

Throws:

NoSuchFieldException - if cls has no public static field named "debug"

Modifies:

cls

printEnabled

public abstract boolean printEnabled()

Test whether calling print() or println() on this debug object will print anything.

Returns:

true if print() prints, false if it's disabled.

reportEnabled

public abstract boolean reportEnabled()

Test whether calling report() on this debug object will print anything.

Returns:

true if report() prints, false if it's disabled.

assertionEnabled

public abstract boolean assertionEnabled()

Test whether calling assertion() on this debug object will do anything.

Returns:

true if assertion() checks assertions, false if it's disabled.

print

public abstract void print(String message)

Print message (if this is enabled for printing)

Parameters:

message - message to print

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints message to output stream, if this is enabled for printing

println

public abstract void println(String message)

Print message (if this is enabled for printing)

Parameters:

message - message to print

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints message to output stream, followed by a newline, if this is enabled for printing

print

public abstract void print(Object obj)

Print an object (if this is enabled for printing)

Parameters:

obj - object to print

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints obj.toString() to output stream, if this is enabled for printing

println

public abstract void println(Object obj)

Print an object (if this is enabled for printing)

Parameters:

obj - object to print

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints obj.toString() to output stream, followed by a newline, if this is enabled for printing

report

public abstract void report(Throwable t)

Print the stack trace of an exception (if this is enabled for reporting exceptions)

Parameters:

t - exception

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints t's stack trace to output stream, if this is enabled for reporting exceptions.

printThreadInfo

public abstract void printThreadInfo()

Print a list of active threads (if this is enabled for printing)

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints list of active threads to output stream, if this is enabled for printing

printStackTrace

public abstract void printStackTrace()

Print stack trace of current execution point (if this is enabled for debugging printing)

Modifies:

this debug object's output stream (by default, System.err)

Effects:

prints stack trace (starting with the call to this.printStackTrace), if this is enabled for printing

assertion

public abstract void assertion(boolean f)

Test an assertion (if this is enabled for assertions)

Parameters:

f - result of assertion expression

Throws:

RuntimeException - if assertion fails and this is Verbose.

Modifies:

this debug object's output stream (by default, System.err)

Effects:

if assertion fails and this is Quiet, then merely reports the assertion failure (in the form of a stack trace) to the output stream.

getOutputStream

public abstract OutputStream getOutputStream()

Returns the OutputStream associated with this debug object.