gumbo.util
Class Debug

java.lang.Object
  |
  +--gumbo.util.Debug

public class Debug

extends java.lang.Object

Utilities for generating "debug" messages to System.err. To use them, debugging must be enabled and configured; and, "print" messages must be included in your code. Debugging can be enabled and configured by calling methods in your code, or through "-D" system properties passed to the JVM on the command line. To use system properties, call Debug.loadAllProperties() before calling any other debug methods.

The default is for debugging to be disabled. Use setEnabled() or the "-Ddebug.enabled=true" property to enable it. To print debug messages from source code, use one of the print???() methods. Depending on the method used and the system properties set, messages will always be printed (if debug is enabled), will only be printed if a message "tag" is set, will only be printed if a message "object" is set, or if both a message tag and object are set.

Debugging messages can be associated with none or more "tags" and optionally an object (typically "this"). For a message to be printed its tag and object, if any, must be in the "global" tag and object tables. A null tag or object is considered a wild card and will be considered present in its respective table. By default, all objects are printed.

Message tags can be added to the table with addTags() or the command line "-Ddebug.tags=???" property, where "???" is none or more delimited tag names. Message objects can be added to the table with addObj(). There is no command line option to add objects since they are considered runtime entities.

In all cases tags are specified as a list of tag tokens delimited by whitespace, commas, or semicolons. Whitespace is trimmed. Ex: "TAG0 TAG1", "TAG0,TAG1", " TAG0, TAG1 " would parse into tags "TAG0" and "TAG1".

Although no messages are printed if debug is disabled, processing for the message arguments is still performed which can adversely affect performance. As such, all debug print statements should be enclosed in an "if(Debug.getEnabled()) {...}" block.

Version:

$Revision: 1.7 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Constructor Summary

Debug()

Method Summary

static void	addObj(java.lang.Object obj) Adds the specified object to the object table.
static void	addTags(java.lang.String tags) Adds the specified tags to the tag table.
static void	clearObjs() Clears the object table.
static void	clearTags() Clears the tag table.
static boolean	hasObj(java.lang.Object obj) Determines if the object is in the object table.
static boolean	hasTag(java.lang.String tags) Determines if any of the tags in the specified tags string are in the tag table.
static boolean	isEnabled() Returns true if debug message printing is enabled.
static boolean	loadAllProperties() Tries to load all Debug system properties.
static boolean	loadPropertyAllObjs() Enables/disables printing all objects according to the "debug.allobjs" system property value.
static boolean	loadPropertyAllTags() Enables/disables printing all tags according to the "debug.alltags" system property value.
static boolean	loadPropertyEnabled() Enables/disables debugging according to the "debug.enabled" system property value.
static boolean	loadPropertyTags() Adds the message tags specified in the "debug.tags" system property to the tag table.
static boolean	print(java.lang.Object obj, java.lang.String tags, java.lang.String message) Prints the specified message, without newline, if any of the specified tags are in the tag table and if the object is in the object table.
static boolean	print(java.lang.String message) Prints the specified message, without newline, regardless of the tag table contents.
static boolean	print(java.lang.String tags, java.lang.String message) Prints the specified message, without newline, if any of the specified tags are in the tag table.
static boolean	println(java.lang.Object obj, java.lang.String tags, java.lang.String message) Prints the specified message, with newline, if any of the specified tags are in the tag table.
static boolean	println(java.lang.String message) Prints the specified message, with newline, regardless of the tag table contents.
static boolean	println(java.lang.String tags, java.lang.String message) Prints the specified message, with newline, if any of the specified tags are in the tag table.
static void	removeObj(java.lang.Object obj) Removes the specified object from the object table.
static void	removeTags(java.lang.String tags) Removes the specified tags from the tag table.
static void	setAllObjs(boolean enabled) Sets whether or not all objects are printed.
static void	setAllTags(boolean enabled) Sets whether or not all tags are printed.
static void	setEnabled(boolean enabled) Sets whether or not debug message printing is enabled.
static java.lang.String	toShortString(java.lang.Object obj) Similar to toString() but the class name is unqualified (returns the remainder of toString() after the last ".").
static java.lang.String	toStackTrace(java.lang.Throwable th) Returns a string containing a throwable's (error, exception) message and stacktrace.
static java.lang.String	toString(java.lang.Object obj) Returns the fully qualified type and hash code (in hex) of an object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Debug

public Debug()

Method Detail

setEnabled

public static void setEnabled(boolean enabled)

Sets whether or not debug message printing is enabled. If not enabled then no output is generated. Accessor methods are unaffected.

Parameters:

enabled - True to enable printing.

isEnabled

public static boolean isEnabled()

Returns true if debug message printing is enabled.

Returns:

True if debug printing enabled.

setAllTags

public static void setAllTags(boolean enabled)

Sets whether or not all tags are printed. If not enabled then only messages whose tags are in the tag table are printed.

Parameters:

enabled - True to enable printing for all tags. The default is false.

setAllObjs

public static void setAllObjs(boolean enabled)

Sets whether or not all objects are printed. If not enabled then only messages whose objects are in the object table are printed.

Parameters:

enabled - True to enable printing for all objects. The default is true.

loadPropertyEnabled

public static boolean loadPropertyEnabled()

Enables/disables debugging according to the "debug.enabled" system property value.

• true - Debugging is enabled.
• false - Debugging is disabled.

Returns:

True if the property was found with a valid value.

loadPropertyAllTags

public static boolean loadPropertyAllTags()

Enables/disables printing all tags according to the "debug.alltags" system property value.

• true - All tags printing is enabled.
• false - All tags printing is disabled.

Returns:

True if the property was found with a valid value.

loadPropertyAllObjs

public static boolean loadPropertyAllObjs()

Enables/disables printing all objects according to the "debug.allobjs" system property value.

• true - All objects printing is enabled.
• false - All objects printing is disabled.

Returns:

True if the property was found with a valid value.

loadPropertyTags

public static boolean loadPropertyTags()

Adds the message tags specified in the "debug.tags" system property to the tag table.

Returns:

True if the property was found with a valid value.

loadAllProperties

public static boolean loadAllProperties()

Tries to load all Debug system properties.

Returns:

True if any properties were found with a valid value.

hasTag

public static boolean hasTag(java.lang.String tags)

Determines if any of the tags in the specified tags string are in the tag table.

Parameters:

tags - List of message tags.

Returns:

True if any of the tags are in the tag table.

addTags

public static void addTags(java.lang.String tags)

Adds the specified tags to the tag table.

Parameters:

tags - List of message tags to be added.

removeTags

public static void removeTags(java.lang.String tags)

Removes the specified tags from the tag table.

Parameters:

tags - List of message tags to be removed. If a tag is not in the table it is ignored.

clearTags

public static void clearTags()

Clears the tag table.

hasObj

public static boolean hasObj(java.lang.Object obj)

Determines if the object is in the object table.

Parameters:

obj - Message object.

Returns:

True if object is in the object table.

addObj

public static void addObj(java.lang.Object obj)

Adds the specified object to the object table.

Parameters:

obj - Object to be added.

removeObj

public static void removeObj(java.lang.Object obj)

Removes the specified object from the object table.

clearObjs

public static void clearObjs()

Clears the object table.

print

public static boolean print(java.lang.String message)

Prints the specified message, without newline, regardless of the tag table contents.

Parameters:

message - Debug message.

Returns:

True if the message was printed.

println

public static boolean println(java.lang.String message)

Prints the specified message, with newline, regardless of the tag table contents.

Parameters:

message - Debug message.

Returns:

True if the message was printed.

print

public static boolean print(java.lang.String tags,
                            java.lang.String message)

Prints the specified message, without newline, if any of the specified tags are in the tag table.

Parameters:

tags - List of message tags. Null for all tags.

message - Debug message.

Returns:

True if the message was printed.

println

public static boolean println(java.lang.String tags,
                              java.lang.String message)

Prints the specified message, with newline, if any of the specified tags are in the tag table.

Parameters:

tags - List of message tags. Null for all tags.

message - Debug message.

Returns:

True if the message was printed.

print

public static boolean print(java.lang.Object obj,
                            java.lang.String tags,
                            java.lang.String message)

Prints the specified message, without newline, if any of the specified tags are in the tag table and if the object is in the object table. Also prints the object at the end of the message as formatted by Object.toString().

Parameters:

obj - Message target object. Typically "this". Null for all targets.

tags - List of message tags. Null for all tags.

message - Debug message.

Returns:

True if the message was printed.

println

public static boolean println(java.lang.Object obj,
                              java.lang.String tags,
                              java.lang.String message)

Prints the specified message, with newline, if any of the specified tags are in the tag table. Also prints the object at the end of the message as formatted by Object.toString().

Parameters:

obj - Message target object. Typically "this". Null for all targets.

tags - List of message tags. Null for all tags.

message - Debug message.

Returns:

True if the message was printed.

toStackTrace

public static java.lang.String toStackTrace(java.lang.Throwable th)

Returns a string containing a throwable's (error, exception) message and stacktrace.

Parameters:

th - Target throwable. Never null.

Returns:

The string. Never null.

toString

public static java.lang.String toString(java.lang.Object obj)

Returns the fully qualified type and hash code (in hex) of an object. Similar in format to Object.toString().

toShortString

public static java.lang.String toShortString(java.lang.Object obj)

Similar to toString() but the class name is unqualified (returns the remainder of toString() after the last ".").