com.ibm.commerce.payments.configurator
Class Trace

java.lang.Object
  |
  +--com.ibm.commerce.payments.configurator.Trace

public class Trace
extends java.lang.Object

Provides a simplified trace utilitary for the Configurator component.


Trace records

The trace facility is based on trace records. Three type of trace records are supported: message, error, exception and entry/exit (step).

A message record is an informational string message. This is the most common type of trace. Use message(String message, int level) to add an message record.

An error record is an entry for an error message. Use error(String message, int level) to add an error record.

An exception is an entry that dumps an exception in the output trace. This type of entry should be used only when an exception cannot be recovered. Use exception(Throwable exception, int level) to add an exception record.

Step records (entry/exit) are used to track the execution flow in method calls. Use finally to ensure that and exit step will be added in methods where exceptions can be thrown.

Step records can be turned on or off independently (setStepTracing(boolean onOrOff)). Use entry(String class, String method, int level) and exit(String class, String method, int level) to add step records.


Trace levels

Every type of trace record supports BASIC, MIDDLE and VERBOSE levels. If the BASIC level is activated, only BASIC records are printed. If MIDDLE level is activated, BASIC and MIDDLE records are printed. If VERBOSE level is activated, BASIC, MIDDLE and VERBOSE records are printed. Use setBasicLevel(), setMiddleLevel() and setVerboseLevel() to specify the trace level. The default level is MIDDLE.


Trace output

Trace can be directed to standard output (setStandardOutputTracing(boolean onOrOff)) and/or to a file (setFileTracing(boolean onOrOff)) independently. By default, the output is directed only to a file. Trace can also be turned on an off using setTracing(boolean onOrOff).


Performance and multi-threading

If expensive operations are required to provide trace, isTracing() should be used to avoid paying for those operations when trace is off.

This trace facility is thread-safe. Concurrent calls to the public methods are supported.


Changing trace defaults

The trace utilitary comes with defaults that are meant to be used in the production version of the code. However, the following properties can be used to change the trace defaults:


Field Summary
static int BASIC
          defines basic tracing level
static int MIDDLE
          defines intermediary tracing level
static int VERBOSE
          defines full tracing level
 
Method Summary
static void entry(java.lang.String className, java.lang.String method, int level)
           Logs a method entry point.
static void error(java.lang.String text, int level)
           Loggs an error message.
static void exception(java.lang.Throwable ex, int level)
           Logs an exception message.
static void exit(java.lang.String className, java.lang.String method, int level)
           Loggs a method exit point.
static boolean isTracing()
           Checks if the tracing is active or not.
static void message(java.lang.String text, int level)
           Loggs a simple message.
static void setBasicLevel()
           Moves the trace level to log only basic trace entries.
static void setFileTracing(boolean onOrOff)
           Turns trace on the file stream on or off.
static void setMiddleLevel()
           Moves the trace level to log basic and middle trace entries.
static void setStandardOutputTracing(boolean onOrOff)
           Turns trace on the output stream on or off.
static void setStepTracing(boolean onOrOff)
           Turns step trace on or off.
static void setTracing(boolean onOrOff)
           Turns global trace on or off.
static void setVerboseLevel()
           Moves the trace level to log basic, middle and verbose trace entries.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BASIC

public static final int BASIC
defines basic tracing level

MIDDLE

public static final int MIDDLE
defines intermediary tracing level

VERBOSE

public static final int VERBOSE
defines full tracing level
Method Detail

isTracing

public static boolean isTracing()

Checks if the tracing is active or not.

This method should be used whenever expensive string operations need to be called to generate an output message. Then, checking if the tracing is on is a good policy to avoid unnecessary string operations.

Returns:
if tracing is on or off

setTracing

public static void setTracing(boolean onOrOff)

Turns global trace on or off.

Parameters:
onOrOff - true means trace on

setStepTracing

public static void setStepTracing(boolean onOrOff)

Turns step trace on or off.

Step trace comprises entry and exit method traces.

Parameters:
onOrOff - true means step trace on

setStandardOutputTracing

public static void setStandardOutputTracing(boolean onOrOff)

Turns trace on the output stream on or off.

Parameters:
onOrOff - true means output stream on

setFileTracing

public static void setFileTracing(boolean onOrOff)

Turns trace on the file stream on or off.

Parameters:
onOrOff - true means file stream on

setBasicLevel

public static void setBasicLevel()

Moves the trace level to log only basic trace entries.


setMiddleLevel

public static void setMiddleLevel()

Moves the trace level to log basic and middle trace entries.


setVerboseLevel

public static void setVerboseLevel()

Moves the trace level to log basic, middle and verbose trace entries.


message

public static void message(java.lang.String text,
                           int level)

Loggs a simple message.

Parameters:
text - the message to be logged
level - the tracing level of the message

error

public static void error(java.lang.String text,
                         int level)

Loggs an error message.

Parameters:
text - the error message to be logged
level - the tracing level of the error message

exception

public static void exception(java.lang.Throwable ex,
                             int level)

Logs an exception message.

Parameters:
ex - the exception to be logged
level - the tracing level of the message

entry

public static void entry(java.lang.String className,
                         java.lang.String method,
                         int level)

Logs a method entry point.

Parameters:
className - the name of the class begin logged
method - the name of the method being logged
level - the tracing level of the entry point

exit

public static void exit(java.lang.String className,
                        java.lang.String method,
                        int level)

Loggs a method exit point.

Parameters:
className - the name of the class begin logged
method - the name of the method being logged
level - the tracing level of the exit point