|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.jthomas.util.Debug
This static class is a substitute for the programmer's favorite debuging tool; inserting 'System.out.println("a="+a);'.
"Debug.out()" compared to "System.out.println()" - 9 fewer keystrokes! - It can be turned on and off at either compile time or runtime. - Any Object can be passed to Debug.out - By default, it will display the Threadname as the 1st output parameter - Output can be written to STDERR and/or to a file. - Can be used inside a Catch block to both print a message and produce a stacktrace. - Can be used to somewhat simulate the C/C++ assert statement. - Can be used to specify different Debug levels. - Can print a stacktrace outside of a try/catch block. - Can print to either stderr and/or file (controlled with set method) - The Thread name can optionally be included in each output. -------------------------------------------------------------- John Thomas October 96 Usage: To have Debug output displayed (by default to stderr) Debug.setDebugOn(true) To have Debug output also written to a file Debug.setDebugFile("debug.txt"); To suppres the output to STDERR (defaults to on) Debug.setDebugOut(false); To control the display of the Thread name(Default=true: Debug.setDebugThreadOn(true/false) To produce debug output just specify a string as a parameter to the Class method "Debug.out(String x)" Instead of a String, you can specify any Java Object and it will print the results of Object.toString(); For example: Debug.out("value=" + value); Vector myvector = new Vector(); .... Debug.out(myvector); To produce a stacktrace both on STDOUT and on the file if being used, when an exception occurs then use the Debug.out(String msg, Exception e) or Debug.out(Exception e) method. If you don't want the stacktrace then use: Debug.out(e.getMessage()); For Example: try { something } catch (Exception e) { Debug.out("Exeception doing something",e); } To produce a stacktrace both on STDOUT and on the file if being used, at anytime without stoping execution then use the Debug.printStackTrace(String description) method. For Example: ... Debug.printStackTrace("entered wierd state"); ... ** ASSERT ** To produce a RuntimeException when certain conditions are not true, then use the Debug.assert(boolean asserted) method or use the Debug.assert(boolean asserted,String debugmsg) method. For Example: ... Debug.assert(thisObj != null); or ... Debug.assert(value < max, "value="+value); Normally assert processing is only done if Debug.ON is true but You can call "Debug.setAssert(true) so that assert is always processed even if setDebugOn(false) is set or defaulted. To use Debug Levels. Debug.setDebugOn(5,true); // turn on level 5. Debug.out(5,"special message"); Levels 3-9 are available for special use Level 0 (or Debug.ALWAYS) is by default true. Level 1 (or Debug.MIN) is the same as the default level Level 2 (or Debug.MAX) will display both MIN and MAX levels setDebugOn(Debug.MAX,true) will turn on all levels. Debug.out(Debug.ALWAYS,"always print"); Debug.out(Debug.MAX,"Print if Debug or Level MIN or MAX is on); Debug.out(5," print only if Debug.setDebug(5,true)" ); To display the Java and OS environment information on the Debug file Debug.environment() This will display the Java Runtime and OS environment. To completely shutoff all Debug output, even exceptions: Debug.quiet(true); Performance considerations Debug when turned on is very expensive because it results in I/O to a file or console..But usually in a Debug mode, one is not so concerned with performance. If the Debug option is false ( setDebugOn(false) ) then a call to Debug.out("msg") will only execute a single if statement inside of the Debug.out method. This is very minimal and a JIT compiler will make it even more minimal. However note that any calls to generate the debug parameter will also be invoked. i.e. Debug.out("name="+userobj.getName()); will invoke the call to the getName() method regardless of of whether Debug is on. However since the Debug ON variable is public, you could code if (Debug.ON) Debug.out("name="+userobj.getName());
Field Summary | |
static int |
ALWAYS
specifies that Debug out should normally be displayed. |
static java.io.PrintWriter |
debugFile
Stream that is used to write the debugFile |
static int |
MAX
specifies that all levels of debug output be displayed. |
static int |
MIN
specifies the default level of Debug output. |
static boolean |
ON
If true, then Format and write the info to stderr, file or both. |
Constructor Summary | |
Debug()
|
Method Summary | |
static void |
asserted(boolean asserted)
Throw a RuntimeException if the argument is false. |
static void |
asserted(boolean asserted,
java.lang.String debugmsg)
Display a message if the argument is false. |
static void |
asserted(boolean asserted,
java.lang.String debugmsg,
boolean fail)
Display a message if the argument is false |
static void |
environment()
Display the System environment information. |
static boolean |
getDebugOut()
Method to let caller control output to STDERR. |
static boolean |
isDebugOn()
Method to let caller test the value of the debug switch. |
static void |
main(java.lang.String[] argv)
Verify that it works. |
static void |
out(boolean primitive)
If ON switch set, display the specified debug info for one of the Java primitive types. |
static void |
out(byte primitive)
|
static void |
out(char primitive)
|
static void |
out(double primitive)
|
static void |
out(float primitive)
|
static void |
out(int primitive)
|
static void |
out(int level,
java.lang.Object debugobj)
If debugOn switch set for specified level, display the specified debug info. |
static void |
out(int level,
java.lang.String debugmsg,
java.lang.Throwable e)
Display the stacktrace info after an exception based on level |
static void |
out(long primitive)
|
static void |
out(java.lang.Object debugobj)
If ON switch set, display the specified debug info. |
static void |
out(short primitive)
|
static void |
out(java.lang.String debugmsg,
java.lang.Throwable e)
Display the stacktrace info after an exception Display the exception info + stacktrace info after an exception This form of Debug.out is always displayed. |
static void |
println(java.lang.String line)
display the specified String unmodified. |
static void |
printStackTrace(java.lang.String debugmsg)
Display the stacktrace info at any time. |
static void |
setAssert(boolean OnOff)
Method to let caller turn the assert processing on or off. |
static void |
setDebugFile(java.lang.String filename)
Method to let caller specify a file to write debug info to. |
static void |
setDebugOn(boolean OnOff)
Method to let caller turn the debug switch on or off. |
static void |
setDebugOn(int level,
boolean OnOff)
Method to let caller turn the debug switch on or off. |
static void |
setDebugOut(boolean OnOff)
Method to let caller control output to STDERR. |
static void |
setDebugThreadOn(boolean OnOff)
Method to let caller turn the thread debug switch on or off. |
static void |
setQuiet(boolean OnOff)
Method to let caller turn off all output |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static boolean ON
One can optimize the efficiency when Debug is not on by coding
if (Debug.ON) Debug(something.toString());
This will avoid calling the toString method of something unless
Debug.ON is set.
One could optimize away even more overhead by making the following "static final"; commenting out where it is set and then recommpiling the code.
public static java.io.PrintWriter debugFile
public static final int ALWAYS
public static final int MIN
public static final int MAX
Constructor Detail |
public Debug()
Method Detail |
public static void setDebugOn(boolean OnOff)
OnOff
- boolean value to turn Debug output on or off.public static void setDebugOut(boolean OnOff)
OnOff
- boolean value to turn STDERR output on or off.public static boolean getDebugOut()
public static void setQuiet(boolean OnOff)
OnOff
- boolean value to turn all output on or off.public static void setDebugOn(int level, boolean OnOff)
level
- This is the level that is being turned on or off.OnOff
- new boolean setting.public static boolean isDebugOn()
public static void setDebugThreadOn(boolean OnOff)
public static void setAssert(boolean OnOff)
public static void setDebugFile(java.lang.String filename)
public static void out(java.lang.Object debugobj)
debugobj
- The parameter is usually a string but it can
also be any other object, in which case it will display
the result of the object.toString() method.public static void println(java.lang.String line)
line
- The parameter is a Stringpublic static void out(int level, java.lang.Object debugobj)
level
- Only display if this level is set true.debugobj
- - The parameter is usually a string but it can
also be any other object, in which case it will display
the result of the object.toString() method.public static void out(boolean primitive)
public static void out(char primitive)
public static void out(byte primitive)
public static void out(short primitive)
public static void out(int primitive)
public static void out(long primitive)
public static void out(float primitive)
public static void out(double primitive)
public static void out(java.lang.String debugmsg, java.lang.Throwable e)
debugmsg
- String to be displayed.e
- Throwable object that is to be displayed.public static void out(int level, java.lang.String debugmsg, java.lang.Throwable e)
level
- Only display if this level is set true.debugmsg
- String to be displayed.e
- Throwable object that is to be displayed.public static void printStackTrace(java.lang.String debugmsg)
debugmsg
- String to be displayed along with the stacktracepublic static void environment()
public static void asserted(boolean asserted)
public static void asserted(boolean asserted, java.lang.String debugmsg)
asserted
- expression that will resolve to a boolean value.debugmsg
- String to be displayed.public static void asserted(boolean asserted, java.lang.String debugmsg, boolean fail)
asserted
- expression that will resolve to a boolean value.debugmsg
- String to be displayed.fail
- If true then throw a Runtime Exception if assertion is false.public static void main(java.lang.String[] argv)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |