com.ibm.ras
Class RASTraceLogger

java.lang.Object
  |
  +--com.ibm.ras.RASObject
        |
        +--com.ibm.ras.RASLogger
              |
              +--com.ibm.ras.RASTraceLogger

public class RASTraceLogger
extends RASLogger
implements RASITraceLogger

The RASTraceLogger is one of two RASLogger sub-classes provided in this package. (The other is RASMessageLogger.) The purpose of tracing is to provide sufficient information to a developer or service team to diagnose a problem remotely (for example, when the application is in production on a customer site). Normally an application will run with tracing turned off. When a problem occurs, it can be turned on to gather the data needed to understand the problem. (A logger's "on/off" state can be controlled by setting its isLogging flag. It might also be controlled through a graphical program, not included in this package.)

When tracing in non-static methods, use the entry, exit, trace and exception methods that take "this" (the object being traced) as the second parameter. This is a convenience to the programmer, as the class name can be derived from any Object. For static methods, an object does not exist. Use the entry, exit, trace and exception methods which take String className as the second parameter.

The set of types that may be used in the entry(), exit() and trace() methods is defined in the RASITraceEvent class. These methods do not validate the type assigned to the trace point, so an error could result in the failure to trace a point.

Note that the entry and exit methods always add RASITraceEvent.TYPE_ENTRY_EXIT to whatever type is selected. It is not necessary to include TYPE_ENTRY_EXIT.

RASTraceLogger has several optional fields which may be included in the message. These fields should not vary among messages produced by a given RASTraceLogger, so they are not included in the entry, exit, trace or exception methods of this class. They can, however, be specified through a RASTraceLogger constructor or by the appropriate "set" and "get" methods of this class. These fields are:

If not specified, each of these fields defaults to an empty string.

See Also:
RASITraceLogger, RASLogger, RASTraceEvent, RASHandler

Fields inherited from class com.ibm.ras.RASLogger
isLogging
 
Constructor Summary
RASTraceLogger()
          Creates a RASTraceLogger.
RASTraceLogger(java.lang.String name)
          Creates a RASTraceLogger.
RASTraceLogger(java.lang.String name, java.lang.String desc)
          Creates a RASTraceLogger.
RASTraceLogger(java.lang.String name, java.lang.String desc, java.lang.String server, java.lang.String client)
          Creates a RASTraceLogger.
 
Method Summary
 void entry(long type, java.lang.Object obj, java.lang.String methodName)
          Traces entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object parm1)
          Traces entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object[] parms)
          Traces entry into a non-static method.
 void entry(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object parm1, java.lang.Object parm2)
          Traces entry into a non-static method.
 void entry(long type, java.lang.String className, java.lang.String methodName)
          Traces entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object parm1)
          Traces entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object[] parms)
          Traces entry into a static method.
 void entry(long type, java.lang.String className, java.lang.String methodName, java.lang.Object parm1, java.lang.Object parm2)
          Traces entry into a static method.
 void exception(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Exception exc)
          Traces an Exception in a non-static method.
 void exception(long type, java.lang.String className, java.lang.String methodName, java.lang.Exception exc)
          Traces an Exception in a static method.
 void exit(long type, java.lang.Object obj, java.lang.String methodName)
          Traces exit from a non-static method.
 void exit(long type, java.lang.Object obj, java.lang.String methodName, java.lang.Object retValue)
          Traces exit from a non-static method.
 void exit(long type, java.lang.String className, java.lang.String methodName)
          Traces exit from a static method.
 void exit(long type, java.lang.String className, java.lang.String methodName, java.lang.Object retValue)
          Traces exit from a static method.
 java.util.Hashtable getConfig()
          Gets the configuration of this object.
 long getTraceMask()
          Gets the mask which defines the set of trace types that will be processed.
 void maskValueChanged()
          Indicates that the value of the handler's trace mask has changed.
 void setConfig(java.util.Hashtable ht)
          Sets the configuration of this object.
 void setTraceMask(long mask)
          Sets the mask which defines the set of trace types that will be processed.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text)
          Traces data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
          Traces data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
          Traces data in a non-static method.
 void trace(long type, java.lang.Object obj, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
          Traces data in a non-static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text)
          Traces data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1)
          Traces data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object[] parms)
          Traces data in a static method.
 void trace(long type, java.lang.String className, java.lang.String methodName, java.lang.String text, java.lang.Object parm1, java.lang.Object parm2)
          Traces data in a static method.
 
Methods inherited from class com.ibm.ras.RASLogger
addHandler, getClient, getHandlers, getServer, isLoggable, isSynchronous, removeHandler, setClient, setServer, setSynchronous
 
Methods inherited from class com.ibm.ras.RASObject
getDescription, getName, setDescription, setName
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RASTraceLogger

public RASTraceLogger()
Creates a RASTraceLogger. The name and description of this object are empty strings.

RASTraceLogger

public RASTraceLogger(java.lang.String name)
Creates a RASTraceLogger. The description of this object is an empty string.
Parameters:
name - The name of this object.

RASTraceLogger

public RASTraceLogger(java.lang.String name,
                      java.lang.String desc)
Creates a RASTraceLogger.
Parameters:
name - The name of this object.
desc - The description of this object.

RASTraceLogger

public RASTraceLogger(java.lang.String name,
                      java.lang.String desc,
                      java.lang.String server,
                      java.lang.String client)
Creates a RASTraceLogger.
Parameters:
name - The name of this object.
desc - The description of this object.
server - The server.
client - The client.
Method Detail

getConfig

public java.util.Hashtable getConfig()
Gets the configuration of this object.
Specified by:
getConfig in interface RASITraceLogger
Returns:
A Hashtable containing the configuration. This object inserts the following key/value pairs into the configuration:
         "traceMask"   The mask which selects the trace types to be
                       processed.
         
All values are Strings. The parent and extensions of this object may add additional keys.
Overrides:
getConfig in class RASLogger

setConfig

public void setConfig(java.util.Hashtable ht)
Sets the configuration of this object. This method is used by a RASManager to initialize a RAS object. It should not be necessary for an application to use this method.
Specified by:
setConfig in interface RASITraceLogger
Parameters:
ht - A Hashtable containing the configuration. This object searches for the following keys:
            "traceMask"   The mask which selects the trace types to be
                          processed.
            
All values are Strings. If a key is not found, that configuration element is not updated. The parent and extensions of this object may add additional keys.
Overrides:
setConfig in class RASLogger

getTraceMask

public long getTraceMask()
Gets the mask which defines the set of trace types that will be processed. Possible values are defined by the logical OR of the RASITraceEvent.TYPE_XXXX constants.
Specified by:
getTraceMask in interface RASITraceLogger
Returns:
The trace mask.

setTraceMask

public void setTraceMask(long mask)
Sets the mask which defines the set of trace types that will be processed. Possible values are defined by the RASITraceEvent.TYPE_XXXX constants. The mask value is not validated against these types.
Specified by:
setTraceMask in interface RASITraceLogger
Parameters:
mask - The trace mask.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName)
Traces entry into a non-static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object parm1)
Traces entry into a non-static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Traces entry into a non-static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.Object[] parms)
Traces entry into a non-static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
parms - An array of parameters passed to the method.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName)
Traces entry into a static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object parm1)
Traces entry into a static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Traces entry into a static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

entry

public void entry(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.Object[] parms)
Traces entry into a static method.
Specified by:
entry in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
parms - An array of elements to be displayed as trace data.

exit

public void exit(long type,
                 java.lang.Object obj,
                 java.lang.String methodName)
Traces exit from a non-static method.
Specified by:
exit in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.

exit

public void exit(long type,
                 java.lang.Object obj,
                 java.lang.String methodName,
                 java.lang.Object retValue)
Traces exit from a non-static method.
Specified by:
exit in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
retValue - The returned value.

exit

public void exit(long type,
                 java.lang.String className,
                 java.lang.String methodName)
Traces exit from a static method.
Specified by:
exit in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.

exit

public void exit(long type,
                 java.lang.String className,
                 java.lang.String methodName,
                 java.lang.Object retValue)
Traces exit from a static method.
Specified by:
exit in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
retValue - The returned value.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text)
Traces data in a non-static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1)
Traces data in a non-static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Traces data in a non-static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object[] parms)
Traces data in a non-static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
text - The trace text.
parms - An array of elements to be displayed with the text.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text)
Traces data in a static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1)
Traces data in a static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object parm1,
                  java.lang.Object parm2)
Traces data in a static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parm1 - An element to be displayed as trace data.
parm2 - An element to be displayed as trace data.

trace

public void trace(long type,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String text,
                  java.lang.Object[] parms)
Traces data in a static method.
Specified by:
trace in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
text - The trace text.
parms - An array of elements to be displayed as trace data.

exception

public void exception(long type,
                      java.lang.Object obj,
                      java.lang.String methodName,
                      java.lang.Exception exc)
Traces an Exception in a non-static method.
Specified by:
exception in interface RASITraceLogger
Parameters:
type - The type of the trace point.
obj - The traced object ("this").
methodName - The name of the traced method.
exc - An exception.

exception

public void exception(long type,
                      java.lang.String className,
                      java.lang.String methodName,
                      java.lang.Exception exc)
Traces an Exception in a static method.
Specified by:
exception in interface RASITraceLogger
Parameters:
type - The type of the trace point.
className - The name of the traced class.
methodName - The name of the traced method.
exc - An exception.

maskValueChanged

public void maskValueChanged()
Indicates that the value of the handler's trace mask has changed.

This method is intended to improve the performance of the RASLogger.isLoggable method. When notified of a change in the value of a handler's mask, the logger can update its internal data, which allows the logger to determine if a RAS event will be logged.

Overrides:
maskValueChanged in class RASLogger