com.ibm.mq.jms.services.psk
Interface Tracer


public interface Tracer

Tracer interface to be implemented by trace service providers. You can define your own trace service provider class for the tracing service either by subclassing PrintWriterTracer or by implementing this interface. Use Trace.setTracer() to tell the trace service to use your new class.


Method Summary
 void dataTrace(int level, java.lang.Object obj, byte[] traceData)
          Provide a formatted hex and ascii dump
 void dumpCallStack()
          Writes a record of the current CallStack to the trace log.
 void dumpCallStack(java.lang.String title)
          Writes a record of the current call stack to the trace log, including a header line for diagnostic purposes.
 void entry(int level, java.lang.Object obj, java.lang.String methodName)
          Traces an entry to a standard (that is, non-static) method if the traceLevel is high enough.
 void entry(int level, java.lang.Object obj, java.lang.String methodName, java.lang.String methodParams)
          Traces an entry to a standard (that is, non-static) method if the traceLevel is high enough.
 void entry(int level, java.lang.String className, java.lang.String methodName)
          Traces an entry to a static method if the traceLevel is high enough.
 void entry(int level, java.lang.String className, java.lang.String methodName, java.lang.String methodParams)
          Traces an entry to a static method if the traceLevel is high enough.
 void exception(int level, java.lang.Object obj, java.lang.String methodName, java.lang.Throwable exc)
          Traces an exception caught in a non-static method if the traceLevel is high enough.
 void exception(int level, java.lang.String className, java.lang.String methodName, java.lang.Throwable exc)
          Traces an exception caught in a static method if the trace level is high enough.
 void exit(int level, java.lang.Object obj, java.lang.String methodName)
          Traces an exit from a standard (that is, non-static) method if the traceLevel is high enough.
 void exit(int level, java.lang.Object obj, java.lang.String methodName, java.lang.String retVal)
          Traces an exit from a standard (that is, non-static) method if the traceLevel is high enough.
 void exit(int level, java.lang.String className, java.lang.String methodName)
          Traces an exit from a static method if the traceLevel is high enough.
 void exit(int level, java.lang.String className, java.lang.String methodName, java.lang.String retVal)
          Traces an exit from a static method if the traceLevel is high enough.
 int getFormat()
          Get the output format for trace entries.
 int getMethodTraceThreshold()
          Gets the threshhold trace level at which system method tracing (within the JVM) is enabled.
 int getTraceLevel()
          Gets the current trace level.
 void setFormat(int format)
          Sets the output format for trace entries.
 void setMethodTraceThreshold(int threshold)
          Sets the threshhold trace level at which system method tracing (within the JVM) is enabled.
 void setTraceLevel(int level)
          Sets the trace level for the current trace.
 void start()
          Called when tracing is turned on to perform any initialisation required.
 void stop()
          Called when tracing is turned off to peform any termination required.
 void trace(int level, java.lang.Object obj, java.lang.String traceText)
          Prints one line of trace from within a non-static method if the traceLevel is high enough
 void trace(int level, java.lang.String className, java.lang.String traceText)
          Prints one line of trace from within a static method if the traceLevel is high enough
 void trace(java.lang.Object obj, java.lang.String traceText)
          Prints one line of trace from within a non-static method.
 void trace(java.lang.String className, java.lang.String traceText)
          Prints one line of trace from within a static method.
 void turnMethodTracingOff()
          Disables Java runtime (JVM) method tracing
 void turnMethodTracingOn()
          Enables Java runtime (JVM) method tracing.
 

Method Detail

dataTrace

public void dataTrace(int level,
                      java.lang.Object obj,
                      byte[] traceData)
Provide a formatted hex and ascii dump

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object requesting the trace (can be null for a static method)
traceData - a byte[] array of the data to be traced

dumpCallStack

public void dumpCallStack()
Writes a record of the current CallStack to the trace log.


dumpCallStack

public void dumpCallStack(java.lang.String title)
Writes a record of the current call stack to the trace log, including a header line for diagnostic purposes.

Parameters:
title - header line written to the trace log with the call stack.

entry

public void entry(int level,
                  java.lang.Object obj,
                  java.lang.String methodName)
Traces an entry to a standard (that is, non-static) method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object generating the trace record
methodName - the name of the method which has just been entered

entry

public void entry(int level,
                  java.lang.Object obj,
                  java.lang.String methodName,
                  java.lang.String methodParams)
Traces an entry to a standard (that is, non-static) method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object generating the trace record
methodName - the name of the method which has just been entered
methodParams - the method parameters, suggested format is name=value, ...

entry

public void entry(int level,
                  java.lang.String className,
                  java.lang.String methodName)
Traces an entry to a static method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the class name of the class generating the trace record
methodName - the name of the method which has just been entered

entry

public void entry(int level,
                  java.lang.String className,
                  java.lang.String methodName,
                  java.lang.String methodParams)
Traces an entry to a static method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the class name of the class generating the trace record
methodName - the name of the method which has just been entered
methodParams - the method parameters (suggested format is name=value, ...)

exception

public void exception(int level,
                      java.lang.Object obj,
                      java.lang.String methodName,
                      java.lang.Throwable exc)
Traces an exception caught in a non-static method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object where the exception was caught
methodName - the name of the method where the exception was caught
exc - the exception itself

exception

public void exception(int level,
                      java.lang.String className,
                      java.lang.String methodName,
                      java.lang.Throwable exc)
Traces an exception caught in a static method if the trace level is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the name of the class where the exception was caught
methodName - the name of the method where the exception was caught
exc - the exception itself

exit

public void exit(int level,
                 java.lang.Object obj,
                 java.lang.String methodName)
Traces an exit from a standard (that is, non-static) method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object generating the trace record
methodName - the name of the method which is being exited

exit

public void exit(int level,
                 java.lang.Object obj,
                 java.lang.String methodName,
                 java.lang.String retVal)
Traces an exit from a standard (that is, non-static) method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object generating the trace record
methodName - the name of the method which is being exited
retVal - the method return value

exit

public void exit(int level,
                 java.lang.String className,
                 java.lang.String methodName)
Traces an exit from a static method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the class name of the class generating this trace record
methodName - the name of the method which is being exited

exit

public void exit(int level,
                 java.lang.String className,
                 java.lang.String methodName,
                 java.lang.String retVal)
Traces an exit from a static method if the traceLevel is high enough.

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the class name of the class generating the trace record
methodName - the name of the method which is being exited
retVal - the method return value

getFormat

public int getFormat()
Get the output format for trace entries.

Returns:
a combination of the trace output format flags: TIME, MILLIS, THREAD_NAME, OBJECT

getMethodTraceThreshold

public int getMethodTraceThreshold()
Gets the threshhold trace level at which system method tracing (within the JVM) is enabled. If trace level is set to this level or above and tracing is turned on, JVM tracing automatically enabled.

Returns:
the threshold value for JVM tracing

getTraceLevel

public int getTraceLevel()
Gets the current trace level. A trace level greater than 0 does not imply that tracing is turned on, it simply indicates the level of tracing in operation when tracing is turned on.

Returns:
the current trace level

setFormat

public void setFormat(int format)
Sets the output format for trace entries. The default output is TRACE_NORMAL, but any combination of the TIME, MILLIS, THREAD_NAME and OBJECT constants can be combined with a logical OR to create the desired formatting.

Parameters:
format - the format value

setMethodTraceThreshold

public void setMethodTraceThreshold(int threshold)
Sets the threshhold trace level at which system method tracing (within the JVM) is enabled. The default value is 5. If the trace level is set to this level or above, and tracing is turned on, then JVM tracing is automatically enabled. It can be enabled explicitly by calling turnMethodTracingOn()

Parameters:
threshold - the threshold value for JVM tracing

setTraceLevel

public void setTraceLevel(int level)
Sets the trace level for the current trace. The default value is "ENTRY_EXIT". The general convention is that the higher the trace level, the more detailed the tracing becomes.

Several trace level constants are defined as a guideline: ERROR_EXCEP, ENTRY_EXIT, EVENT, DATA and DUMP.

You do not need to call this method explicitly if you set the level when you call turnTracingOn(int level).

Parameters:
level - the desired level of tracing

start

public void start()
Called when tracing is turned on to perform any initialisation required.


stop

public void stop()
Called when tracing is turned off to peform any termination required.


trace

public void trace(int level,
                  java.lang.Object obj,
                  java.lang.String traceText)
Prints one line of trace from within a non-static method if the traceLevel is high enough

Parameters:
level - the traceLevel at which this data is written to the trace log
obj - the object generating the trace record
traceText - the text information to be printed to the trace

trace

public void trace(int level,
                  java.lang.String className,
                  java.lang.String traceText)
Prints one line of trace from within a static method if the traceLevel is high enough

Parameters:
level - the traceLevel at which this data is written to the trace log
className - the class name of the class generating the trace log
traceText - the text information to be printed to the trace

trace

public void trace(java.lang.Object obj,
                  java.lang.String traceText)
Prints one line of trace from within a non-static method. If tracing is turned on, the record is written to the trace log regardless of the trace level setting.

Parameters:
obj - the object generating the trace record
traceText - the information to be printed to the trace

trace

public void trace(java.lang.String className,
                  java.lang.String traceText)
Prints one line of trace from within a static method. If tracing is turned on, the record is written to the trace log regardless of the trace level setting.

Parameters:
className - the name of the class generating the trace record
traceText - the text information to be printed to the trace

turnMethodTracingOff

public void turnMethodTracingOff()
Disables Java runtime (JVM) method tracing


turnMethodTracingOn

public void turnMethodTracingOn()
Enables Java runtime (JVM) method tracing. (needs to run under java_g)


(c) Copyright IBM Corp. 2005. All Rights Reserved.