com.bea.p13n.util.debug
Class Debug

java.lang.Object
  com.bea.p13n.util.debug.Debug

public abstract class Debug
extends Object

Developer's debugging aid.

Use to add debugging messages to code (vs. logging important events). The debugging can be turned on or off with a simple property (in debug.properties file or with -D switch on the command line). The debug messages that this prints all have location information automatically added (i.e. class, method, and line number).

Using this class makes it easy to:

• Turn debugging on and off without recompiling code
• Enable debugging output for a single class or entire subsystem
• Find where debugging messages are comming from

For simplicity, this class acts as both the Debug API abstract base class as well as the factory implementation (getInstance methods).

Example code usage:

   package com.bea.example;
   import com.bea.p13n.util.debug.Debug;
   class MyClass 
   {
     // Instance of debug object for debugging (if turned on)
     // Using this pattern makes it easy to know the debug "switch"
     // for any class
     private static final Debug debug = Debug.getInstance( MyClass.class );
 
     MyClass()
     {
         // debug class creation event
         debug.here()
     }
     void myMethod()
     {
       // output a debugging message along with class, method & line number
       debug.out("This is some message");
       
       // output a debugging message followed by object value
       // use this rather than ("message" + val) to avoid
       // expression evaluation (string concatenation) when debug is off
       debug.out("The value is:", val);

       // Avoid expression evaluations by using debug.ON or debug.isOn()
       if (debug.ON)
       {
          Object thing = doSomeCalculations();
          debug.out( "The thing " + thing + " is the calculation result." );
       }
     }
   }
 

When debugging is turned on, the debug output for the above example will look something like this:

  *** com.bea.example.MyClass.(MyClass.java:<13>) ***
  [com.bea.example.MyClass.myMmethod():18] This is some message
  [com.bea.example.MyClass.myMmethod():23] The value is 42
  [com.bea.example.MyClass.myMmethod():29] The thing kryten is the calculation result.
 

Debugging is off by default. To switch debugging on, create a file named debug.properties in the default working directory. Alternately, you can set the system property debug.properties to the name of your debug properties file. For example:

  java -Ddebug.properties=/home/me/mydebug.properties ... 
 

To turn on debugging for a class, add an entry to the debug properties file for that class and set the value to on. So, to turn logging on for the class com.bea.example.MyClass, add the following line to the properties file:

   com.bea.example.MyClass: on
 

Actually, to turn logging on, you can set the property to anything except false, off, no or 0 (these values can be used to explicitly turn logging off). But for clarity and consistency, it is suggested that you use the values on and off in the properties file.

If you wish to turn on debugging for all the classes in some package, you can do that, too. To enable the ability to turn debugging on by package name, turn on the debug property usePackageNames. Then, you can turn on debugging for an entire package (and it's child packages). For example, to turn on debugging for all classes in the com.bea.example.* package, put the following in debug.properties:

   # turn on debugging by package names
   usePackageNames: on

   # turn on debugging for everyting under com.bea.example package
   # Note that you do not use wildcards, just mention the package
   com.bea.example: on
 

When you are using package names, you can get finer control because more specific names take precedence over the less specific. For example, if you want to turn on debugging for the entire com.bea.example.* package except for MyClass and the internal package (with the exception of one class), put the following in the properties:

   # turn on package names for debugging
   usePackageNames: on

   # turn on debugging for everyting under com.bea.example package
   com.bea.example: on

   # turn off debugging for MyClass
   com.bea.example.MyClass: off
   
   # turn off debugging in the entire internal package
   com.bea.example.internal: off
 
   # Except turn debugging back on for internal.DebugThisClass
   com.bea.example.internal.DebugThisClass: on
 

In the above examples, debug output will be sent to System.err. To redirect debug output to a file, set the debug property out.file to the name of an output file. The debug output will be appended to the end of that file unless you also set out.file.append=off, in which case the file will be deleted first. For example:

   # append output to mydebug.log file rather than System.err
   out.file = mydebug.log
 
   # send this debugging to mydebug.log
   com.bea.example.DebugMeToFile: on
 

As an alternative to the debug.properties file, System properties may be used if the property name is prefixed with "debug.". For example:

  java -Ddebug.out.file=mydebug.log -Ddebug.com.bea.example.MyClass=on  ... 
 

For performance reasons, Debug is by default not reloadable. The debug properties settings are in effect for the life of the JVM. To change debuging (i.e. to turn it on or off for some class or package), you normally have to restart the JVM with different debug properties.

This reloading behavior can be changed with the debug property reloadable set to on in debug.properties or with -Ddebug.reloadable=on on the java command line. If reloadable is set when the JVM is initially started, then debugging properties that are loaded from debug.properties (or system properties) can be changed at runtime without restarting the JVM. The reloadable property can not be changed on at runtime - it must be set initially to take effect.

To change debug properties, edit the code>debug.properties file and call Debug.reload() (i.e. from a JSP page or other runtime component).

Note that reloadable debug can be convenient for development, but even when it is not outputting any messages it does come at some (unquantified) cost, and thus should not be used in production or other performance sensitive systems (i.e. load or performance tests).

Field Summary

boolean

ON Is debugging on for this instance?

Method Summary

static String	getDebugPropertyFile() Return the name of the debug.properties file.
static Debug	getInstance(Class theClass) Get an implementation of this class based on a Class.
static Debug	getInstance(String theName) Factory method to get an implementation of this class based on a property name.
static Debug	getPrintingDebug() Return a Debug implementation that will always output debug messages regardless of any debug property settings.
void	here() Output a "you are here" message.
boolean	isDebugOnDynamic() Dynamic computation of debugging on/off state.
static boolean	isDebugOnGlobally() Return true if Debug is on at all.
boolean	isOn() Is debugging on? In most circumstances, you do not need to test for this - you can just call one of the out() methods.
static boolean	isReloadable() Return true if Debug is reloadable (reloadable property was set initially).
void	out(Object obj) Output an object's string representation as a debug message.
void	out(String message) Ouptut a debug message, prepended with location information (where the message comes from).
void	out(String message, boolean bool) Output a message and a boolean as a debug message.
void	out(String message, long num) Output a message and a number as a debug message.
void	out(String message, Object obj) Output a message and an object as a debug message.
void	out(String message, Throwable throwable) Output a message with an exception stack trace.
void	out(Throwable throwable) Output an exception stack trace as a debug message The exception's message is output, followed by a space and the stack trace.
static void	reload() If reloadable is set, reload the debug.properties file (and system properties).

Methods inherited from class java.lang.Object

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

Field Detail

ON

public final boolean ON

Is debugging on for this instance?

See Also

isOn()

Method Detail

getInstance

public static Debug getInstance(Class theClass)

Get an implementation of this class based on a Class. This method just calls getInstance( theClass.getName() ).

See class documentation for information on how the name is used to turn debugging on and off with the debug.properties file.
The suggested usage in a class is:

   private static final Debug debug = Debug.getInstance( MyClass.class );
 

Parameters

theClass - Class name of the class being debugged

Returns

A Debug object for debugging the named class. The returned instance will implement debugging (on or off) based on the debug properties settings.

See Also

getInstance(java.lang.String)

getInstance

public static Debug getInstance(String theName)

Factory method to get an implementation of this class based on a property name. It is recommended that you use the name of the class being debugged as the property name.

See class documentation for information on how the name is used to turn debugging on and off with the debug.properties file.

Parameters

theName - Property name on which to base the returned instance

Returns

A Debug object for debugging based on the named property. The returned instance will implement debugging (on or off) based on the debug properties settings.

See Also

getInstance(java.lang.Class)

reload

public static void reload()

If reloadable is set, reload the debug.properties file (and system properties). This does nothing if reloadable was not set initially. It also outputs a debug message "Debug Reloaded."

getDebugPropertyFile

public static String getDebugPropertyFile()

Return the name of the debug.properties file. This is either debug.properties in the current working directory or the value of the System property debug.properties. Does not indicate in any way if that file exists or is in use.

See Also

isDebugOnGlobally()

isReloadable

public static boolean isReloadable()

Return true if Debug is reloadable (reloadable property was set initially).

isDebugOnGlobally

public static boolean isDebugOnGlobally()

Return true if Debug is on at all. Debug is on if there is a debug.properties file and/or if any System debug properties are set.

getPrintingDebug

public static Debug getPrintingDebug()

Return a Debug implementation that will always output debug messages regardless of any debug property settings.

isOn

public final boolean isOn()

Is debugging on? In most circumstances, you do not need to test for this - you can just call one of the out() methods. Debug is optimized for this case to be inexpensive when debugging is turned off.

Use this isOn() check (or the ON field) when you have to perform some computations or string concatenations only if debugging is turned on. Testing for on/off will let you avoid these computations when debugging is turned off. See the class documentation for an example.

When the reloadable property is set, this will always return true, regardless of the current setting for this instance. The assumption here is that the computations you are doing (string concatenations, etc) will be faster than the debug check. It is not suggested to use the debug ON flag to cause a change in behavior.

Returns

true if debugging is on, false if it is off

See Also

ON, isDebugOnDynamic()

isDebugOnDynamic

public boolean isDebugOnDynamic()

Dynamic computation of debugging on/off state. In most circumstances, you do not need to test for this - you can just call one of the out() methods. Debug is optimized for this case to be inexpensive when debugging is turned off.

Use this isDebugOnDynamic() when you have to perform some computations or string concatenations only if debugging is turned on, and you don't want to compute these if debug is reloadable. Testing for on/off will let you avoid these computations when debugging is turned off. See the class documentation for an example.

When the reloadable property is set, this will test on each call if a call to out() would print anything. Use this test when the calculations you are making for debugging are relatively expensive and would significantly degrade performance when using reloadable debug.

When the reloadable property is unset, this method does the same thing as isOn().

Returns

true if debugging is on, false if it is off

See Also

isOn(), ON

out

public void out(String message)

Ouptut a debug message, prepended with location information (where the message comes from).

The output format for all out() methods is:

   [package.ClassName.method():lineNumber] message
 

Only the method name is output, not its signature (arguments). The method name for constructors is "<init>", and for static initializers is "<cinit>". The line number will not be output if it is unavailable (i.e. the class was compiled with no debugging information).

Parameters

message - The debug message to output

out

public void out(Object obj)

Output an object's string representation as a debug message. The string representation of the object is output using StringUtils.toString, which is like String.valueOf for everything except arrays (which are output in a more readable form.

Parameters

obj - An object to use as a debug message

See Also

StringUtils.toString(java.lang.Object)

out

public void out(String message,
                Object obj)

Output a message and an object as a debug message. The output consists of the message followed by a space and then the string representation of the object.

The string representation of the object is output using StringUtils.toString, which is like String.valueOf for everything except arrays (which are output in a more readable form.

Parameters

message - The debug message to output

obj - An object to append to the message

See Also

StringUtils.toString(java.lang.Object)

out

public void out(String message,
                long num)

Output a message and a number as a debug message. The output consists of the message followed by a space and then the string representation of the number.

Parameters

message - The debug message to output

num - A number to append to the message

out

public void out(String message,
                boolean bool)

Output a message and a boolean as a debug message. The output consists of the message followed by a space and then the string representation of the boolean.

Parameters

message - The debug message to output

bool - A boolean to append to the message

out

public void out(Throwable throwable)

Output an exception stack trace as a debug message The exception's message is output, followed by a space and the stack trace.

This is like calling out(throwable.getMessage(), throwable).

Parameters

throwable - An exception whose stack trace will be used as debug output

out

public void out(String message,
                Throwable throwable)

Output a message with an exception stack trace. The output consists of the message followed by a space and then the exception's stack trace. The first line of the stack trace will follow the message, on the same line as the class, method, and line number information. The remainder of the stack trace will follow on subsequent lines of output.

Parameters

message - The debug message to output

throwable - An exception whose stack trace will be appended to the message

here

public void here()

Output a "you are here" message. This is useful for code-path sanity checks. It is probably more useful to actually output a message, since those also have line number information. But the different format of this output can sometimes prove useful. For example, you might put a here() call in a constructor or static initializer to track object or class creation.

The output format is:

  
   *** package.ClassName.method() @ FileName.java:lineNumber ***
 

Only the method name is output, not its signature (arguments). The method name for constructors is "<init>", and for static initializers is "<cinit>". The file name and/or line number will not be output if they are unavailable (i.e. the class was compiled with no debugging information).