gov.nih.nlm.nls.utils
Class ThreadedDebug

java.lang.Object
  gov.nih.nlm.nls.utils.ThreadedDebug

public class ThreadedDebug

extends java.lang.Object

$Id: ThreadedDebug.java,v 1.4 2003/10/31 18:10:24 divita Exp $ TSDebug is a bunch of static methods to aid in debugging.

Description: java source file.

TSDebug includes methods to trace invocations into and out of constructors and methods in a pretty printed way when running an application. It has options to control what traced methods are printed by flags picked up from a debug.fla configuration file or a file defined by the system property DBG_FLAGS.

These methods are automatticly added to java source code created via a source code stubber (skel.Skel) when the -jD or -kD option is used to create skelaton classes and methods. The flags associated with each skelaton method is also automaticlly created and assigned by the stubber appliation.

Implementer's note here: The counter file for the classes is

/nfsvol/nls/aux5/nls/asta/config/DebugNumbers.cfg in our Unix environment and

c:\DEBUG\DebugNumbers.cfg on PC's.

Basicly, programs that have the following added to them:

 +--Foo.java ----
 | public void foo()
 | {
 |     Debug.dfname("foo");             <------------------dfname-
 |     Debug.denter(DT1000);            <------------------denter-
 |      .
 |      .
 |     Debug.dpr(DF10001, "A debug print message");  <--------dpr-
 |      .
 |     Debug.dexit(DT1000);             <------------------dexit--
 | }
 +---------------           

   that get invoked in a directory that has a debug.fla file with the line(s)
   
 +--debug.fla----
 |            3        // General Flag to turn on all Debugging Print statements
 |         1000        // DT for method foo 
 |         1001        // DF for method foo 
 +---------------           

  will have the an output that looks like the following when run:
 
 +---------------           
 | e:\mtp\debug\java foo
 | -->+main
 | 
 | ------> +foo
 |           A debug print message
 | ------> -foo
 | -->-main
 | 
 +---------------           
 

All debug messages go out to standard out.

Note that the debug.fla file has to be recognized via the CURRENT DIRECTORY where the program gets kicked off from. This may be sticky to figure out when running in a debugger or from a web applicaiton where it is not obvious where the current directory is. There is one special flag number, "3" that turns on all the flags. One can turn on flags by having their number appear as the first characters in the line. Lines can have comments to the right of the flags to note what the flag is to. comments can start with # or // for example the following could appear in a debug.fla file:

              
              3        // General Flag to turn on all Debugging Print statements
 

Flags are turned off by having a ! or a # before the flag number in the file. For instance, the following line could appear in the debug.fla file:

              !3       // General Flag to turn on all Debugging Print statements is disabled.
 

These print statements can be stripped from a source file via the application StripDebug, provided that there are no assignments done in the statements themselves, and the messages don't span lines.

History

Fri Jun 02 14:12:51 EDT 2000, divita Initial Version

Notes: These methods are intended to be used in single threaded applications only. The way they are implemented, will cause any multi-threaded application to syncronize on each command. (not good). One of these days I'll fix this.

Constructor Summary

ThreadedDebug()

Method Summary

static void	denter(int traceCode) Method denter tags the method with a flag number.
static void	dexit(int traceCode) dexit is a method that is found at the end of each method, and is married to the denter method.
static void	dfname(java.lang.String methodName) Method dfname adds a method or constructor name to the stack of method names.
static boolean	dIsSet(int flag) dIsSet returns true if the flag is set
static void	dpr(int flag, java.lang.String message) dprint and dpr are methods to send messages to intended to be debugging messages.
static void	dprint(int flag, java.lang.String message) dprint and dpr are methods to send messages to intended to be debugging messages.
static void	warning(java.lang.String message) warning is a convient way to send a debugging message, regardless whether the flag is set or not.

Methods inherited from class java.lang.Object

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

Constructor Detail

ThreadedDebug

public ThreadedDebug()

Method Detail

dfname

public static void dfname(java.lang.String methodName)

Method dfname adds a method or constructor name to the stack of method names. dfname appears at the top of every method and constructor.

Parameters:

methodName - The name of the method or constructor.

denter

public static void denter(int traceCode)

Method denter tags the method with a flag number. Flag numbers are automaticly created by a stubbing program skel. Flag numbers are created as private final static int's (constants in other languages) The flags passed in to denter are those which can be specified in the debug.fla file to be turned on and off. When a flag is turned on, as the application passes through this code, a pretty printed print statement will be printed for this method.

Parameters:

traceCode - A flag specified when the method is stubbed.

dprint

public static void dprint(int flag,
                          java.lang.String message)

dprint and dpr are methods to send messages to intended to be debugging messages. dpr and dprint take a flag and a message as parameters. At runtime, if the flag has been set, a pretty printed message will print out as the code passes this statement. If the flag is not set or is set off, then no message is printed.

Parameters:

flag -

message -

dpr

public static void dpr(int flag,
                       java.lang.String message)

dprint and dpr are methods to send messages to intended to be debugging messages. dpr and dprint take a flag and a message as parameters. At runtime, if the flag has been set, a pretty printed message will print out as the code passes this statement. If the flag is not set or is set off, then no message is printed.

Parameters:

flag -

message -

dIsSet

public static boolean dIsSet(int flag)

dIsSet returns true if the flag is set

Parameters:

flag -

Returns:

boolean message

warning

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

warning is a convient way to send a debugging message, regardless whether the flag is set or not. warning is useful to be embedded in the exception sections, where one should always report some useful message.

Parameters:

message -

dexit

public static void dexit(int traceCode)

dexit is a method that is found at the end of each method, and is married to the denter method. denter and dexit methods determine the level of indentation when pretty printing. The dexit method unindents what the denter method indents.

Parameters:

traceCode -