com.ibm.tspaces
Class Debug

java.lang.Object
  |
  +--com.ibm.tspaces.Debug

public class Debug

extends java.lang.Object

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.
 --------------------------------------------------------------
 
 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());
 

Note: This version of the Debug.java class was slightly modified to fit into the TSpaces codebase It was origially written for use in another non IBM project by the author.

Author:

John Thomas

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	assert(boolean asserted) Throw a RuntimeException if the argument is false
static void	assert(boolean asserted, java.lang.String debugmsg) Display a message if the argument is false
static void	assert(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	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 exception info + stacktrace info after an exception This form of Debug.out is always displayed.
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

ON

public static boolean ON

If true, then Format and write the info to stderr, file or both

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.

debugFile

public static java.io.PrintWriter debugFile

Stream that is used to write the debugFile

ALWAYS

public static final int ALWAYS

specifies that Debug out should normally be displayed.

MIN

public static final int MIN

specifies the default level of Debug output.

MAX

public static final int MAX

specifies that all levels of debug output be displayed.

Constructor Detail

Debug

public Debug()

Method Detail

setDebugOn

public static void setDebugOn(boolean OnOff)

Method to let caller turn the debug switch on or off.

Parameters:

OnOff - boolean value to turn Debug output on or off.

setDebugOut

public static void setDebugOut(boolean OnOff)

Method to let caller control output to STDERR.

Parameters:

OnOff - boolean value to turn STDERR output on or off.

setQuiet

public static void setQuiet(boolean OnOff)

Method to let caller turn off all output

Parameters:

OnOff - boolean value to turn all output on or off.

setDebugOn

public static void setDebugOn(int level,
                              boolean OnOff)

Method to let caller turn the debug switch on or off. for specified levels

Parameters:

level - This is the level that is being turned on or off.

OnOff - new boolean setting.

isDebugOn

public static boolean isDebugOn()

Method to let caller test the value of the debug switch.

Returns:

Returns the boolean value of the Debug setting.

setDebugThreadOn

public static void setDebugThreadOn(boolean OnOff)

Method to let caller turn the thread debug switch on or off.

setAssert

public static void setAssert(boolean OnOff)

Method to let caller turn the assert processing on or off.

setDebugFile

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

Method to let caller specify a file to write debug info to. It will also set the Debug switch to true.

Parameters:

file - File name to be used to write the debug output to.

out

public static void out(java.lang.Object debugobj)

If ON switch set, display the specified debug info. If the specified Object is an Exception then it will be treated as if Debug ON switch was set.

Parameters:

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.

out

public static void out(int level,
                       java.lang.Object debugobj)

If debugOn switch set for specified level, display the specified debug info. If debugOut is true - use Ssystem.er.println If debugFile is set, write to the specified file and then flush the buffers.

Parameters:

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.

out

public static void out(boolean primitive)

If ON switch set, display the specified debug info for one of the Java primitive types. (boolean,char,byte,short,int,long float,double)

Parameters:

A - java primitive type that is to be displayed.

out

public static void out(char primitive)

out

public static void out(byte primitive)

out

public static void out(short primitive)

out

public static void out(int primitive)

out

public static void out(long primitive)

out

public static void out(float primitive)

out

public static void out(double primitive)

out

public static void out(java.lang.String debugmsg,
                       java.lang.Throwable e)

Display the exception info + stacktrace info after an exception This form of Debug.out is always displayed.

Parameters:

debugmsg - String to be displayed.

e - Throwable object that is to be displayed.

out

public static void out(int level,
                       java.lang.String debugmsg,
                       java.lang.Throwable e)

Display the stacktrace info after an exception based on level

Parameters:

level - Only display if this level is set true.

debugmsg - String to be displayed.

e - Throwable object that is to be displayed.

printStackTrace

public static void printStackTrace(java.lang.String debugmsg)

Display the stacktrace info at any time.

Parameters:

debugmsg - String to be displayed along with the stacktrace

environment

public static void environment()

Display the System environment information.

assert

public static void assert(boolean asserted)

Throw a RuntimeException if the argument is false

Parameters:

expression - that will resolve to a boolean value.

assert

public static void assert(boolean asserted,
                          java.lang.String debugmsg)

Display a message if the argument is false

Parameters:

asserted - expression that will resolve to a boolean value.

debugmsg - String to be displayed.

assert

public static void assert(boolean asserted,
                          java.lang.String debugmsg,
                          boolean fail)

Display a message if the argument is false

Parameters:

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.

main

public static void main(java.lang.String[] argv)

Verify that it works.