# com.bea.p13n.util.debug
Debug Class

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).

Hierarchy
  `Object`
  `Debug`

## Field Summary

`public final boolean` | `ON` Is debugging on for this instance?

## Method Summary

`public static `String`` | `getDebugPropertyFile`() Return the name of the debug.properties file.
`public static `Debug`` | `getInstance`(`Class` theClass) Get an implementation of this class based on a Class.
`public static `Debug`` | `getInstance`(`String` theName) Factory method to get an implementation of this class based on a property name.
`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.
`public static boolean` | `isDebugOnGlobally`() Return true if Debug is on at all.
`public final boolean` | `isOn`() Is debugging on?
`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).
`public void` | `out`(`Object` obj) Output an object's string representation as a debug message.
`public void` | `out`(`String` message, `Object` obj) Output a message and an object as a debug message.
`public void` | `out`(`String` message, long num) Output a message and a number as a debug message.
`public void` | `out`(`String` message, boolean bool) Output a message and a boolean as a debug message.
`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.
`public void` | `out`(`String` message, `Throwable` throwable) Output a message with an exception stack trace.
`public static synchronized void` | `reload`() If `reloadable` is set, reload the `debug.properties` file (and system properties).

Methods 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?

Related Topics

``Debug.isOn()``

## Method Detail

### getDebugPropertyFile() Method

    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

``Debug.isDebugOnGlobally()``

### getInstance(Class) Method

    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.

Related Topics

``Debug.getInstance(String)``

### getInstance(String) Method

    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.

Related Topics

``Debug.getInstance(Class)``

### getPrintingDebug() Method

    public static synchronized Debug getPrintingDebug()

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

### here() Method

    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).

### isDebugOnGlobally() Method

    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.

### isOn() Method

    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.

#### Returns

true if debugging is on, false if it is off

Related Topics

``Debug.ON``

### isReloadable() Method

    public static boolean isReloadable()

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

### out(String) Method

    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(Object) Method

    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

Related Topics

``StringUtils.toString(Object)``

### out(String, Object) Method

    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

Related Topics

``StringUtils.toString(Object)``

### out(String, long) Method

    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(String, boolean) Method

    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(Throwable) Method

    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(String, Throwable) Method

    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

### reload() Method

    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."