com.ibm.commerce.ras

Class WASTrace

java.lang.Object

com.ibm.commerce.ras.WASTrace

public class WASTrace
extends java.lang.Object

Wrapper for the WebSphere trace facility. It allows various types of trace records to be written to the WebSphere Application Server trace file. To use WASTrace, your classpath should contain this class and WebSphere's ras.jar.

Although this class can be used to write trace records, it cannot be used for specifying trace settings. Users should use the administrators console to set trace settings for particular components and to specify how the trace will be collected by the system. The default application server setting is that all trace is disabled.

No initialization of WASTrace is needed before you begin invoking the trace methods. However, each of these methods requires a logger name that must be unique within the Commerce product. Logger names can be dotted separated to ensure uniqueness (for example, ShoppingCart, payments.MPF, payments.PDP).

Under WebSphere Application Server, you must use the administrator's console to specify the trace setting as well as the output file for your trace records. The location for the trace file is specified on the trace settings page in both WebSphere Application Server and WebSphere Studio.

Calling applications should condition each trace call with the isTracing() method to ensure optimal performance when tracing is disabled:

   if (isTracing(LOGGER_NAME)) WASTrace.debug(LOGGER_NAME,...);
 

There are three WebSphere trace settings:

• event
• entryExit
• debug

Using the WebSphere Administrator's console you can enable or disable these settings for each Commerce trace logger. You can also choose combinations of these settings.

Calls to the debug() methods will write to the trace log only when the debug trace setting is enabled for the specified logger.

Calls to the entry and exit methods will write to the trace log only when the entryExit is enabled for the specified logger.

Calls to the event() and exception methods will write to the trace log when any trace setting is enabled for the specified logger.

See Also:

WASLog

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COPYRIGHT IBM copyright notice field.

Constructor Summary

Constructors

Constructor and Description
WASTrace()

Method Summary

Modifier and Type	Method and Description
static void	debug(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.String text) Writes a trace record containing the specified text if debug tracing for the specified logger is enabled.
static void	debug(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm) Writes a trace record containing the specified text and parameters if debug tracing for the specified logger is enabled.
static void	debug(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms) Writes a trace record containing the specified text and parameters if debug tracing for the specified logger is enabled.
static void	entry(java.lang.String loggerName, java.lang.String className, java.lang.String methodName) Writes a trace method entry record if entryExit tracing for the specified logger is enabled.
static void	entry(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.Object parm) Writes a trace method entry record if entryExit tracing for the specified logger is enabled.
static void	entry(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.Object[] parms) Writes a trace method entry record if entryExit tracing for the specified logger is enabled.
static void	event(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.String text) Writes a trace record containing the specified text if any tracing is enabled for the specified logger.
static void	event(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms) Writes a trace record containing the specified text and parameters if any tracing is enabled for the specified logger.
static void	exception(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.Throwable t) Writes a trace record containing the specified exception if any tracing is enabled for the specified logger.
static void	exit(java.lang.String loggerName, java.lang.String className, java.lang.String methodName) Writes a trace method exit record if entryExit tracing for the specified logger is enabled.
static void	exit(java.lang.String loggerName, java.lang.String className, java.lang.String methodName, java.lang.Object retValue) Writes a trace method exit record containing the specified return value if entryExit tracing for the specified logger is enabled.
static com.ibm.ras.RASTraceLogger	getTraceLogger(int loggerIndex) Gets the RAS trace logger object associated with the specified index value.
static com.ibm.ras.RASTraceLogger	getTraceLogger(java.lang.String loggerName) Gets the RAS trace logger object for the specified component
static com.ibm.ras.RASTraceLogger	getTraceLogger(java.lang.String loggerName, int loggerIndex) Gets the RAS trace logger object for the specified component name.
static boolean	isTracing(int loggerIndex) Indicates whether the trace logger is currently enabled to trace records.
static boolean	isTracing(java.lang.String loggerName) Indicates whether the trace logger is currently enabled to trace records.

Methods inherited from class java.lang.Object

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

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT

IBM copyright notice field.

See Also:

Constant Field Values

Constructor Detail

WASTrace

public WASTrace()

Method Detail

isTracing

public static final boolean isTracing(java.lang.String loggerName)

Indicates whether the trace logger is currently enabled to trace records. All calls to one of the trace methods in this class should be conditioned using this method as follows:

   if (isTracing(LOGGER_NAME)) WASTrace.debug(LOGGER_NAME,...);
 

This will improve the performance of the system since the arguments of the debug(...) method will not be evaluated when tracing is disabled.

Parameters:

loggerName - the unique name for the trace logger

Returns:

true if tracing for the specified logger is enabled; false otherwise

isTracing

public static final boolean isTracing(int loggerIndex)

Indicates whether the trace logger is currently enabled to trace records. All calls to one of the trace methods in this class should be conditioned using this method as follows:

   if (isTracing(LOGGER_INDEX)) WASTrace.debug(LOGGER_NAME,...);
 

This will improve the performance of the system since the arguments of the debug(...) method will not be evaluated when tracing is disabled.

Parameters:

loggerIndex - the component that has previously been associated with a trace logger.

Returns:

true if tracing for the specified logger is enabled; false otherwise

debug

public static void debug(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String text)

Writes a trace record containing the specified text if debug tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

text - the text to be written to the trace record

debug

public static void debug(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String text,
                         java.lang.Object parm)

Writes a trace record containing the specified text and parameters if debug tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

text - the text to be written to the trace record

param - the data to be written to the trace record.

debug

public static void debug(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String text,
                         java.lang.Object[] parms)

Writes a trace record containing the specified text and parameters if debug tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

text - the text to be written to the trace record

params - the data to be written to the trace record. Each object in the array should respond appropriately to the toString() method.

entry

public static void entry(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName)

Writes a trace method entry record if entryExit tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

entry

public static void entry(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.Object parm)

Writes a trace method entry record if entryExit tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

parm - the data to be written to the trace record

entry

public static void entry(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.Object[] parms)

Writes a trace method entry record if entryExit tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

parms - the data to be written to the trace record

exit

public static void exit(java.lang.String loggerName,
                        java.lang.String className,
                        java.lang.String methodName)

Writes a trace method exit record if entryExit tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

exit

public static void exit(java.lang.String loggerName,
                        java.lang.String className,
                        java.lang.String methodName,
                        java.lang.Object retValue)

Writes a trace method exit record containing the specified return value if entryExit tracing for the specified logger is enabled.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

retValue - the value to be returned by the calling method

event

public static void event(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String text)

Writes a trace record containing the specified text if any tracing is enabled for the specified logger.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

text - the text to be written to the trace record

event

public static void event(java.lang.String loggerName,
                         java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String text,
                         java.lang.Object[] parms)

Writes a trace record containing the specified text and parameters if any tracing is enabled for the specified logger.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

text - the text to be written to the trace record

params - the data to be written to the trace record. Each object in the array should respond appropriately to the toString() method.

exception

public static void exception(java.lang.String loggerName,
                             java.lang.String className,
                             java.lang.String methodName,
                             java.lang.Throwable t)

Writes a trace record containing the specified exception if any tracing is enabled for the specified logger.

Parameters:

loggerName - the unique name for the trace logger

className - the name of the calling class

methodName - the name of the calling method

t - the Throwable to report in the trace log

getTraceLogger

public static final com.ibm.ras.RASTraceLogger getTraceLogger(java.lang.String loggerName)

Gets the RAS trace logger object for the specified component

Parameters:

loggerName - the component that identifies the trace logger

Returns:

the RAS trace logger object for the specified component

getTraceLogger

public static final com.ibm.ras.RASTraceLogger getTraceLogger(java.lang.String loggerName,
                                                              int loggerIndex)

Gets the RAS trace logger object for the specified component name. Also associates the specified index value with the specified name.

Parameters:

loggerName - the component that identifies the trace logger

loggerIndex - the index value to be associated with the specified name.

Returns:

the RAS trace logger object for the specified component

getTraceLogger

public static final com.ibm.ras.RASTraceLogger getTraceLogger(int loggerIndex)

Gets the RAS trace logger object associated with the specified index value.

Parameters:

loggerIndex - the component that has previously been associated with a trace logger.

Returns:

the RAS trace logger object for the specified component