Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright © 2006 BEA Systems, Inc. All Rights Reserved
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006 BEA Systems, Inc. All Rights Reserved