18

Debugging Tools

Features of JCDebug  Classes and Scripts  Methods

Removing JCDebug Statements from Your Code  Examples

---

18.1 Features of JCDebug

JCDebug is a utility class that allows you to add debugging statements to your source code, in order to facilitate development tasks. Once the statements are in the code, the debugging mechanism can easily be turned on or off. To activate normal debug output, simply call setEnabled(true); to turn off debugging without removing it from the source, call setEnabled(false) to globally disable JCDebug printing. To permanently remove the debugging code from the source, just the jcdebug.pl perl script, located in the JCLASS_HOME/bin directory.

It is also possible to group debugging statements by providing a tag parameter along with the text to be printed. For example:

JCDebug.println("tag1", "This is printed when setEnabled(true) and   setTag(\"tag1\") are in effect.").

Thus, if you wish to enable print statements marked by parameter tag1, call setTag("tag1"). If you wish to turn on debugging print statements with various tags, call setTags(String new_tags[]), passing in an array of tag names. Initially, the array of tag names is null, which means that no tagged statements will be output. Thus, once some tags have been set, they can all be turned off by calling setTag(null).

Another useful construct is the concept of "levels." The advantage of this is that by calling, for example, setLevel(2), you will avoid seeing any debug messages marked 3 or below. This is useful for controlling the amount of detail you are viewing without removing the debug information.

Note that JClass distribution bytecode does not contain any references to JCDebug.

JCDebug helps you accomplish the following:

• Place multi-level print statements in your code for debugging purposes and remove them after testing is complete.
• Force a stack trace to occur at any point in your code.
• Optionally use a Perl script to place /*DEBUG_START*/ ... /*DEBUG_END*/ blocks in your code. The debug statements are removed or commented out at ship-time using the PERL script JCLASS_HOME/bin/jcdebug.pl.

---

18.2 Classes and Scripts

com.klg.jclass.util.JCDebug	Class containing static methods for assertions and debug statements.
jcdebug.pl	The Perl script that removes or comments out JCDebug statements from source code.

---

18.3 Methods

Printing debug information

You can define a numerical order-of-importance to your print statements. Print statements labeled with lower numbers are deemed to be more important than those with higher-numbered labels. By setting a global print level variable at 3, for example, all print statements labeled with a number higher than three will be ignored. Those labeled with a print level variable of 1, 2, or 3 will all be printed.

Also, it's possible to supply a list of tags. All print statements with print level variables matching a String in the list will be processed, all other print statements will be ignored.

setPrintStream()	Sets the output stream to use. The default is System.out.
getPrintStream()	Returns the PrintStream currently in use.
println()	Prints debug information on the current output stream.
println   (String text)	Always prints a message, unless debugging is turned off.
println(int   plevel, String   text)	The int parameter is for level-controlled diagnostic printing. Any print statement with a plevel greater than the currently set print level is not printed.
println(String   ptag, String   text)	The ptag parameter for tag-controlled diagnostic printing. Any print statement with a ptag matching than the currently set tag list is printed.
println(int   plevel, String   ptag, String   text)	Prints the text according to level and tag filter options. This method is a combination of println(int plevel, String text) and println(Sting ptag, String text).
setEnabled(true)	Activates debug output.
isEnabled()	Determines if debugging is on or off.
setLevel(int   new_level)	Output occurs for statements marked with the specified level or lower. To see all debug statements, set new_level to a very large number.
getLevel()	Returns the level that determines what gets printed. All levels less than or equal to the returned integer are printed.
setTag("myString")	Sets one tag. A second call to setTag() causes the first tag to be forgotten.
setTags(arrayOfSt  rings)	Sets the array of tags to use for the debugging session.

Notes on tags and level numbers:

• If you do not supply a tag as one of the parameters in your print statement, the tag is deemed to be null. Statements with null tags are always printed as long as debugging is enabled.
• As long as you get a match from the level number or the tags you'll have some diagnostic printout.
• You don't have to use either tags or level numbers. You can simply use unadorned JCDebug.println statements. In this case, you don't have any selectivity other than being able to turn debugging on and off.

Forcing a stack trace

The following methods help force a stack trace:

printStackTrace()	Forces a stack trace at the current location.
printStackTrace(   String s)	Forces a stack trace at the current location, and prints an identifying message as a header.
printStackTrace(   String ptag,   Throwable t)	Prints a stack trace for the specified exception if the specified tag is currently enabled.

---

18.4 Removing JCDebug Statements from Your Code

To remove the JCDebug statements from your code, you will need a Perl interpreter. If you don't have one, it is available at the central Web site for the Perl community (http://www.perl.com).

Running the Perl script

The script you will need to call is jcdebug.pl. It has three options: -e, -d, and -r. The -e option enables your debugging statements. It places markers in the form of comments before and after each debug statement, leaving the statement itself exposed to the Java compiler. These markers have the form /* JCDEBUG_START* / and /* JCDEBUG_END */, with the JCDebug statement in between.

The -d option removes the inner pair of matching * /   /* brackets to form one long comment which includes the JCDebug statement.

The -r option completely removes all JCDebug statements. You might want to use this option just before shipping the final product. Just realize that once the debug statements are removed using this option, they can't be recovered.

Here's an example of a command to delete JCDebug statements by turning them into comments:

perl jcdebug.pl -d MyCode.java

After executing this command, all JCDebug statements begin with /* JCDEBUG_START and end with JCDEBUG_END */. Since this is the syntax for the start and end of a comment, anything between these tags is not compiled.

Execute the following command:

perl jcdebug.pl -e MyCode.java

This will modify the file by replacing the inner pair of matching * /   /* brackets so that all JCDebug statements begin with /* JCDEBUG_START */ and end with /* JCDEBUG_END */. The JCDebug statement itself is no longer part of the comment.

As was mentioned above, the script removes all lines with JCDebug.print in them, and any import com.klg.jclass.util.JCDebug statements that may exist. If you just want to turn off the debugging code without removing it from your source, call setEnabled(false) to globally disable JCDebug assertions and printing.

---

18.5 Examples

This example illustrates the following points about the use of JCDebug:

• JCDebug.setEnabled(true) must be in effect for the debug mechanism to be turned on.
• If tags are used, JCDebug.setTag() controls which tagged print statements are active. The example uses tag2 and tag3 as arbitrary labels. Print statements involving tag2 will be active, but those involving tag3 will not.

import com.klg.jclass.util.JCDebug;

public class TestJCDebug {

public static void main(String args[])
{
  JCDebug.setEnabled(true);
  System.out.println("Starting the test:");

  //Set a tag so that all JCDebug statements with this tag will print
  JCDebug.setTag("tag2");

  //These should print
  JCDebug.println("Debugging is on so this should be printed!");
  JCDebug.println("tag2", "Label tag2 is enabled, " + "so this should be
            printed.");

  //This should not print because it does not match the tag
  JCDebug.println("tag3", "The tag for this print statement is tag3 " +
            "so this should not be printed.");

  //Now turn off debugging
  JCDebug.setEnabled(false);

  //The following two lines will not be printed.
  JCDebug.println("Debugging is off. This should not be printed!");
  JCDebug.println("tag2", "This label is enabled, but debugging is off, "
            + "so this should not be printed");
}

}

The output from this test program is reproduced here.

Starting the test:
Debugging is on so this should be printed!
Label tag2 is enabled, so this should be printed.