com.ccg.util
Class Debug

java.lang.Object
  com.ccg.util.Debug

public final class Debug
extends Object

Class to allow for easy removal of debug output messages.

Java does not offer precompilation directives. This makes it difficult to build different versions of the software from the same set of source files (there are no #if/#else/#endif directives).

It is still desirable at times to create a "debug" version of your software. Typically the debug version will output a lot of text messages describing what is going on. Some of the desired capabilities of such a system include:

• The ability to easily output "debug" messages.
• The ability to remove all of the "debug" code.
• The option to use hard coded ASCII message, or localized messages via the java.text.MessageFormat class.
• The ability to set the verbosity level of debug messages.

This class attempts to provide these features for you. Here is a simple example of how this might be done:

 import com.ccg.util.*;

 class Foo {
   public static void main(String[] args) {
     Log.init("Example",new CommandLine(args));

     Debug.log(1,"Foo Starting");

     for (int i = 0; i < args.length; i++) {
                                // if debug enabled at level 5
       if (Debug.ENABLED && Debug.isEnabledFor(5)) {
         Object[] args = { new Number(i), args[i] };
         Debug.log(5,"debugArgList","arg[{0}] = \"{1}\".",args);
       }
     }
   }
 }

 

Please refer to the LogDebug example program (and its source code) for a decent working example of using this class with localization values.

IMPORTANT NOTE: For those that care about optimization and minimizing code size. It is recommended use the Debug.ENABLED test and to avoid the log methods entirely - I will probably deprecate them. For example, consider the three following manners of logging debug output:

                                // Option A: the BAD way!
 Debug.log(3,"Time is: "+new java.util.Date());

                                // Option B: the better way
 if (Debug.isEnabledFor(3)) {
   Debug.out("Time is: "+new java.util.Date());
 }

                                // Option C: the BEST way
 if (Debug.ENABLED && Debug.isEnabledFor(3)) {
   Debug.out("Time is: "+new java.util.Date());
 }

 

All of the above will generate the same debug output when the debug level is set to three or higher. HOWEVER, Option A will ALWAYS create the string (which is expensive) AND invoke the log(int, java.lang.String, java.lang.String, java.lang.Object[]) method even when the debug output won't be output (waste of CPU and time).

Option B and Option C are much more efficient as they determine whether debug output is needed prior to generating it. However, Option C is the best way to do it, because if Debug.ENABLED is set to true, the compiler strips out the "Debug.ENABLED &&" portion of the if clause - leaving the exact same code as Option B. But, when Debug.ENABLED is set to false, the compiler strips out the entire block of code (reducing both code size and the invocation of Debug.isEnabledFor(3).

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

Log

Field Summary

(package private) static int	_verbosityLevel
static int	DISABLE Turn off debug output.
static boolean	ENABLED Determine if debugging code is enabled or disabled.

Constructor Summary

Debug()

Method Summary

static StringBuffer	getStackTrace(String first, Throwable e) Simple function to get Exception stack trace in StringBuffer form.
static String	getStackTrace(Throwable e) Simple function to get Exception stack trace in String form.
static int	getVerbosity() Get the current verbosity level.
static boolean	isEnabledFor(int dlev) Simple check to see if debug output is enabled for a specific level.
static void	log(int dlev, String msg) Debug output sans Internationalization capabilities.
static void	log(int vlev, String key, String dMsg, Object[] args) Log a debug message.
static void	out(String msg) Debug output sans Internationalization capabilities and no verbosity check.
static void	out(String key, String dMsg, Object[] args) Output a debug message.
static void	out(String msg, Throwable e) Debug output with Exception sans Internationalization capabilities and no verbosity check.
static void	setVerbosity(int level) Changes the "verbosity" (amount of) debug output that is generated.

Methods inherited from class java.lang.Object

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

Field Detail

ENABLED

public static final boolean ENABLED

Determine if debugging code is enabled or disabled. This variable can be used to determine if debugging output is enabled or not. One typically uses this variable if they need to do some formatting prior to logging a debug message. If you use this variable in a test condition, the compiler should be able to remove all of the "debug" code when the debugging information is disabled. The following stub demonstrates:

                                // Compiler can strip out ALL of this
                                // when ENABLED is set to false
 if (Debug.ENABLED && Debug.isEnabledFor(9)) {
   String expensive = formatCurrentData();
   Debug.out("Current Data:"+expensive);
 }


Since:
  
1.0
See Also:
Log.log(int,String,String,Object[]), 
Constant Field Values

DISABLE

public static final int DISABLE

Turn off debug output. This constant is used as a parameter to setVerbosity(int) to disable the output of the Debug.Log() messages.

Since:

1.0

See Also:

setVerbosity(int), Constant Field Values

_verbosityLevel

static int _verbosityLevel

Constructor Detail

Debug

public Debug()

Method Detail

setVerbosity

public static final void setVerbosity(int level)

Changes the "verbosity" (amount of) debug output that is generated. By default, the output of debug messages is disabled. Before any of the debug output is generated, this member function must be called to set the "verbosity" level of the debug output. This output level is in the range of 0-9 with higher numbers producing more output.

Parameters:

level - New verbosity level from 0 (most disabled) up to 9 (all enabled), or DISABLE to turn off all debug output.

Since:

1.0

See Also:

log(int, java.lang.String, java.lang.String, java.lang.Object[])

getVerbosity

public static final int getVerbosity()

Get the current verbosity level.

Returns:

The current verbosity level (0-9) or DISABLE.

Since:

1.0

See Also:

setVerbosity(int)

isEnabledFor

public static boolean isEnabledFor(int dlev)

Simple check to see if debug output is enabled for a specific level. This routine allows one to determine if debug output will be allowed for a specific level. It is typically used in an if clause when you want to skip construction of your debug messages if they wouldn't result in output anyway. This can greatly enhance the performance of your code as shown in the following example:

 void foo(int sum_to) {
                                // We skip a lot of code by checking first
   if (Debug.isEnabledFor(9)) {
      long sum=0;               // compute an expensive value
      for (int i = 0; i < sum_to; i++) sum += i;

      Object[] args = { 
        new java.util.Date(), 
        new Integer(sum_to), 
        new Long(sum) 
      };

      Debug.log(9,"sumMessage","{0}: Summing up to {1} resulted in {2}",
                    args);
   }
 }
 

Parameters:

dlev - The debug level you are intending on using.

Returns:

true if output for the specified debug level will actually be logged (false if not).

Since:

1.0

See Also:

setVerbosity(int)

log

public static void log(int vlev,
                       String key,
                       String dMsg,
                       Object[] args)

Log a debug message. This routine is a front end to Log.log(). You invoke it from your code when you want to output a "debug" message. If the debug output is enabled, and the verbosity level associated with you debug output is below the currently set level, then your message will be logged with its log level set to Log.DEBUG. However, if the optimized version of this source code is in place, then if everything works out correctly, the compiler will completely remove your "debug" output. This should allow developers to include diagnostic output for development builds, which will automatically be stripped out by the compiler for release builds.

Parameters:

vlev - Verbosity level. This should be in the range of [0-9]. Output will only be logged if this level is less than the current verbosity level. This was done to mimic a lot of GNU code.

key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.

dMsg - Default string message (if key is null or locale specific message isn't found).

args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.

Since:

1.0

See Also:

ENABLED, setVerbosity(int)

out

public static final void out(String key,
                             String dMsg,
                             Object[] args)

Output a debug message. This routine is a front end to Log.log(). You invoke it from your code when you want to output a "debug" message. This method assumes that you've already checked the "verbosity" level for debug output (probably with isEnabledFor(int)).

Parameters:

key - Used to look up any locale specific string. If null or the locale specific string is not found, then dMsg will be used for the string.

dMsg - Default string message (if key is null or locale specific message isn't found).

args - If non-null, up to 10 java.text.MessageFormat parameters that can be subsituted into the message.

Since:

1.0

See Also:

isEnabledFor(int), setVerbosity(int)

log

public static final void log(int dlev,
                             String msg)

Debug output sans Internationalization capabilities. Since debug messages are normally intended for inhouse debug development, often it isn't necessary to worry about internationalization of these types of messages. This is a convenience function which allows one to simply specify a verbosity level and text string message.

Parameters:

vlev - Verbosity level. This should be in the range of [0-9]. Output will only be logged if this level is less than the current verbosity level.

msg - Message to log (no localization will be performed).

Since:

1.0

See Also:

Log.log(int,String,String,Object[])

out

public static final void out(String msg,
                             Throwable e)

Debug output with Exception sans Internationalization capabilities and no verbosity check. Since debug messages are normally intended for inhouse debug development, often it isn't necessary to worry about internationalization of these types of messages. This is a convenience function which allows one to simply specify a text string message as well as a exception.

Parameters:

msg - Message to log (no localization will be performed).

e - Exception which you would like to have a stack trace added to the log (no localization will be performed).

Since:

1.0

See Also:

Log.log(int,String,String,Object[]), isEnabledFor(int)

out

public static final void out(String msg)

Debug output sans Internationalization capabilities and no verbosity check. Since debug messages are normally intended for inhouse debug development, often it isn't necessary to worry about internationalization of these types of messages. This is a convenience function which allows one to simply specify a text string message.

Parameters:

msg - Message to log (no localization will be performed).

Since:

1.0

See Also:

Log.log(int,String,String,Object[]), isEnabledFor(int)

getStackTrace

public static String getStackTrace(Throwable e)

Simple function to get Exception stack trace in String form. I was finding myself wanting to look at the Exception stack traces during development. Sometimes I wanted them in a string form. This function does it for you (its a static function, so anyone can use it).

Parameters:

e - Throwable object (typically an Exception) to get full stacktrace in string form from.

Returns:

Output of e.printStackTrace() in string form.

Since:

1.0

See Also:

getStackTrace(String,Throwable), log(int, java.lang.String, java.lang.String, java.lang.Object[])

getStackTrace

public static StringBuffer getStackTrace(String first,
                                         Throwable e)

Simple function to get Exception stack trace in StringBuffer form. While getStackTrace(Throwable) was pretty dang handy, I kept finding times when I wanted to precede the stack trace with my own text and then possibly append my own text following the stack trace. This method provides these features. You don't have to worry about passing null parameters either (it just ignores null values - no output for them).

Parameters:

s - String to print before stack trace (you can pass null if you don't want any leading string passed).

e - Throwable object (typically an Exception) to get full stacktrace in string form from. This can be null.

Returns:

A StringBuffer (in case you want to append further information) with the leading string (if specified) printed on its own line followed by the stack trace output of the exception (if not null)

Since:

1.0

See Also:

log(int, java.lang.String, java.lang.String, java.lang.Object[])