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:
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: onActually, 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: onWhen 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).
Object
Debug
Field Summary |
public final boolean |
|
Method Summary |
public static |
|
public static |
|
public static |
|
public static synchronized |
|
public void |
|
public static boolean |
|
public final boolean |
|
public static boolean |
|
public void | |
public void | |
public void | |
public void | |
public void | |
public void | |
public void | |
public static synchronized void |
|
Methods from class java.lang. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public final boolean ON
Related Topics
Method Detail |
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.
Related Topics
public staticGet an implementation of this class based on a Class. This method just callsDebug
getInstance(Class
theClass)
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 );
Related Topics
public staticFactory 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.Debug
getInstance(String
theName)
See class documentation for information on how the name is used
to turn debugging on and off with the debug.properties
file.
Related Topics
public static synchronized Debug
getPrintingDebug()
Return a Debug implementation that will always output debug
messages regardless of any debug property settings.
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).
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.
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.
Related Topics
public static boolean isReloadable()Return true if Debug is reloadable (
reloadable
property
was set initially).
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] messageOnly 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).
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.
Related Topics
public void out(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.String
message,Object
obj)
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.
Related Topics
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.
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.
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)
.
public void out(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.String
message,Throwable
throwable)
public static synchronized 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."