com.klg.jclass.util
Class JCDebug

java.lang.Object
  |
  +--com.klg.jclass.util.JCDebug

public class JCDebug

extends Object

A useful mechanism for managing assertions and debug prints. A perl script is provided to remove references to this class to produce production code. See com.klg.jclass/util/scripts/rmdebug.pl.

The script removes any line containing JCDebug.<print|assert> AND any import com.klg.jclass.util.JCDebug statements that may exist. Optionally you may call setEnabled(false) to globally disable JCDebug printing.

By calling setEnabled(true), you can activate normal debug output. If you wish to view code marked "mycode", then call setTag("mycode").

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 greater. This is useful for controlling the amount of detail you are viewing without removing the debug information.

Note: JClass distribution bytecode does not contain any references to this class.

Field Summary

protected static boolean	enabled
protected static int	level
protected static PrintStream	stream
protected static String[]	tags

Constructor Summary

JCDebug()

Method Summary

static void	assertThat(boolean condition) Invoked to assert that a particular condition is true.
static void	assertThat(boolean condition, String message) Invoked to assert that a particular condition is true and throw an exception with the specified message if it is not.
static int	getLevel() Returns the level that determines what gets printed.
static PrintStream	getPrintStream() Returns the PrintStream currently in use.
static String[]	getTags() Gets the tags currently used to filter output.
static boolean	isEnabled() Returns whether or not Debug output is enabled.
protected static boolean	isPrintableLevel(int plevel) If the passed-in level is less than or equal to the set level, then we deem the level to be printable.
protected static boolean	isPrintableTag(String tag) If the passed-in tag is in the tags list or the tag is null, then we deem the tag to be printable; otherwise it is not.
static void	print(int plevel, String text) Equivalent to calling print(plevel, null, text).
static void	print(int plevel, String ptag, String text) Prints the text according to level and tag filter options.
static void	print(String text) Equivalent to calling print(0, null, text).
static void	print(String ptag, String text) Equivalent to calling "print(0, ptag, text)".
static void	println(int plevel, String text) Equivalent to calling println(plevel, null, text).
static void	println(int plevel, String ptag, String text) Prints the text followed by a newline according to level and tag filter options.
static void	println(String text) Equivalent to calling println(0, null, text).
static void	println(String ptag, String text) Equivalent to calling println(0, ptag, text).
static void	printStackTrace() Useful routine to force a stack trace at the current location by generating and catching a mock NullPointerException.
static void	printStackTrace(String s) Useful routine to force a stack trace at the current location by generating and catching a mock NullPointerException.
static void	printStackTrace(String ptag, Throwable t) Prints a stack trace for the specified exception, but only if the specified tag is currently enabled.
static void	setEnabled(boolean e) Controls global enable/disable of Debug printing.
static void	setLevel(int new_level) Sets the level of debug information to print.
static void	setPrintStream(PrintStream pstream) Sets the output stream to use.
static void	setTag(String tag) Convienience method to allow setting of one tag.
static void	setTags(String[] new_tags) Sets the list of tags to match against when determining which debug print statements to output.

Methods inherited from class java.lang.Object

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

Field Detail

enabled

protected static boolean enabled

tags

protected static String[] tags

level

protected static int level

stream

protected static PrintStream stream

Constructor Detail

JCDebug

public JCDebug()

Method Detail

setEnabled

public static void setEnabled(boolean e)

Controls global enable/disable of Debug printing. By default this is false and should be turned on to see the debug output.

Parameters:

e - Should Debug printing be enabled?

isEnabled

public static boolean isEnabled()

Returns whether or not Debug output is enabled.

Returns:

whether Debug printing is enabled

setPrintStream

public static void setPrintStream(PrintStream pstream)

Sets the output stream to use. The default is System.out.

Parameters:

pstream - the new output stream

getPrintStream

public static PrintStream getPrintStream()

Returns the PrintStream currently in use.

Returns:

the current output stream

setLevel

public static void setLevel(int new_level)

Sets the level of debug information to print. Output will only occur for statements marked with the specified level or less. Print statements that do not specify a level are always printed.

Parameters:

new_level - the new level of debug information to print

getLevel

public static int getLevel()

Returns the level that determines what gets printed.

Returns:

the current level of debug information to print

See Also:

setLevel(int)

setTags

public static void setTags(String[] new_tags)

Sets the list of tags to match against when determining which debug print statements to output. If this list is null (the default), then no tagged print statements will be output.

Parameters:

new_tags - the new list of tags

setTag

public static void setTag(String tag)

Convienience method to allow setting of one tag. This tag will replace any old tags.

Parameters:

tag - the new tag

getTags

public static String[] getTags()

Gets the tags currently used to filter output.

Returns:

the current list of tags to filter output

assertThat

public static final void assertThat(boolean condition)

Invoked to assert that a particular condition is true. Useful if you need a pre JDK 1.4 assert mechanism.

Parameters:

condition - the condition to assert true or false

assertThat

public static final void assertThat(boolean condition,
                                    String message)

Invoked to assert that a particular condition is true and throw an exception with the specified message if it is not. Useful if you need a pre JDK 1.4 assert mechanism.

Parameters:

condition - the condition to assert true or false

message - the message to print if the assertion fails

printStackTrace

public static void printStackTrace()

Useful routine to force a stack trace at the current location by generating and catching a mock NullPointerException.

printStackTrace

public static void printStackTrace(String s)

Useful routine to force a stack trace at the current location by generating and catching a mock NullPointerException.

Parameters:

s - a String to display at the top of the trace

printStackTrace

public static void printStackTrace(String ptag,
                                   Throwable t)

Prints a stack trace for the specified exception, but only if the specified tag is currently enabled.

Parameters:

ptag - the "tag" to be used to determine whether to print the trace

t - exception to display

print

public static void print(int plevel,
                         String ptag,
                         String text)

Prints the text according to level and tag filter options.

Parameters:

plevel - the "level" of the print command

ptag - the "tag" associated with the print command (note that the tag must be in the tags list for the data to be output); a tag of null means that the line should always be printed

text - the text to print

print

public static void print(int plevel,
                         String text)

Equivalent to calling print(plevel, null, text).

Parameters:

plevel - the "level" of the print command

text - the text to print

print

public static void print(String ptag,
                         String text)

Equivalent to calling "print(0, ptag, text)".

Parameters:

ptag - the "tag" associated with the print command (note that the tag must be in the tags list for the data to be output); a tag of null means that the line should always be printed

text - the text to print

print

public static void print(String text)

Equivalent to calling print(0, null, text).

Parameters:

text - the text to print

println

public static void println(int plevel,
                           String ptag,
                           String text)

Prints the text followed by a newline according to level and tag filter options.

Parameters:

plevel - the "level" of the print command

ptag - the "tag" associated with the print command (note that the tag must be in the tags list for the data to be output); a tag of null means that the line should always be printed

text - the text to print

println

public static void println(int plevel,
                           String text)

Equivalent to calling println(plevel, null, text).

Parameters:

plevel - the "level" of the print command

text - the text to print

println

public static void println(String ptag,
                           String text)

Equivalent to calling println(0, ptag, text).

Parameters:

ptag - the "tag" associated with the print command (note that the tag must be in the tags list for the data to be output); a tag of null means that the line should always be printed

text - the text to print

println

public static void println(String text)

Equivalent to calling println(0, null, text).

Parameters:

text - the text to print

isPrintableLevel

protected static boolean isPrintableLevel(int plevel)

If the passed-in level is less than or equal to the set level, then we deem the level to be printable.

Parameters:

plevel - the level to be tested

Returns:

whether the level is printable

isPrintableTag

protected static boolean isPrintableTag(String tag)

If the passed-in tag is in the tags list or the tag is null, then we deem the tag to be printable; otherwise it is not.

Parameters:

tag - the tag to be tested

Returns:

whether tag is printable