com.ibm.ims.rds
Class XMLTrace

java.lang.Object
  |
  +--com.ibm.ims.rds.XMLTrace
All Implemented Interfaces:
java.io.Serializable

public class XMLTrace
extends java.lang.Object
implements java.io.Serializable

XMLTrace provides tracing facilities to document the flow of control in an IMS Java application.

By default tracing is disabled. To enable tracing call the XMLTrace.enable() method with optional arguments for a trace name and the tracing level.

While enabling IMS Tracing, the user can specify by means of an optional parameter to the enable() method, the level of detail produced in the resulting trace. This trace level ranges from the lowest level (the default) of logging only Remote Database Services generated exceptions (TRACE_EXCEPTIONS) to logging all details including IMS Java library calls (TRACE_DATA3). Each progressive level includes the all tracing from the previous level and adds any events or information in the new level. The available levels are:

TRACE_EXCEPTIONS
causes tracing of exceptions
TRACE_CTOR1
causes tracing of level 1 constructors
TRACE_METHOD1
causes tracing of level 1 methods and constructors
TRACE_DATA1
causes tracing of level 1 parameters, return values, methods, and constructors
TRACE_CTOR2
causes tracing of level 2 constructors and all level 1 entries
TRACE_METHOD2
causes tracing of level 2 methods and constructors, and all level 1 entries
TRACE_DATA2
causes tracing of level 2 parameters, return values, methods, constructors, and all level 1 entries
TRACE_CTOR3
causes tracing of level 3 constructors and all level 1 and level 2 entries
TRACE_METHOD3
causes tracing of level 3 methods and constructors, and all level 1 and level 2 entries
TRACE_DATA3
causes tracing of level 3 parameters, return values, methods, constructors, and all level 1 and level 2 entries
After tracing is complete, the IMS Tracing should be closed by calling the XMLTrace.close() method. This will add closing tags to the XML trace as well as close any files opened for tracing.

Some of the IMS library supplied packages implement tracing using "Trace" subclasses. These subclasses re-implement the methods in the base class needing to be traced by wrapping XMLTrace calls around the calls to the base class methods. In addition, prior to instantiating an object implementing tracing, a test is made to see if tracing is enabled. If tracing is enabled, the "Trace" subclass is instantiated instead of the base class. This style of tracing is limited to classes that hide their constructors and support object creation using "createInstance" style methods on the class (or on a related class).

Tracing the entry point of constructors in Java is made difficult by the language requirement that the first line of a constructor be a call to its super class constructor. The result of this behavior is that the trace will show an entry and exit of the base class constructor prior to showing an entry to the derived class constructor.

See Also:
Serialized Form

Field Summary
static int libTraceLevel
          Trace level for code.
protected static int maxBinaryLength
           
static int TRACE_CTOR1
          Causes tracing of level 1 constructors
static int TRACE_CTOR2
          Causes tracing of level 2 constructors and all level 1 entries.
static int TRACE_CTOR3
          Causes tracing of level 3 constructors and all level 1 and level 2 entries.
static int TRACE_DATA1
          Causes tracing of level 1 parameters, return values, methods, and constructors.
static int TRACE_DATA2
          Causes tracing of level 2 parameters, return values, methods, constructors, and all level 1 entries.
static int TRACE_DATA3
          Causes tracing of level 3 parameters, return values, methods, constructors, and all level 1 and level 2 entries.
static int TRACE_EXCEPTIONS
          Causes tracing of Exception constructors
static int TRACE_METHOD1
          Causes tracing of level 1 methods and constructors.
static int TRACE_METHOD2
          Causes tracing of level 2 methods and constructors, and all level 1 entries.
static int TRACE_METHOD3
          Causes tracing of level 3 methods and constructors, and all level 1 and level 2 entries.
protected static java.lang.String traceName
          Name of the Application being traced
static boolean traceOn
          Value indicating whether tracing is turned on or not.
 
Method Summary
static void close()
          Closes the trace file.
protected static void closeRootTag()
          Adds the closing root tag for this trace run.
static XMLTrace currentTrace()
          Returns the XMLTrace object for the current thread.
static void enable()
          Enables XML Tracing with default Name and TraceLevel
static void enable(int level)
          Enables XML Tracing with the default root element name, TracedApp.
static void enable(java.lang.String name)
          Enables XML Tracing with the default trace level, XMLTrace.TRACE_EXCEPTIONS
static void enable(java.lang.String name, int level)
          Enables XML Tracing with the specified root element and trace level.
static int getTraceLevel()
          Returns the current level of IMS Tracing.
 void logConstructorEntry(java.lang.String constructorName)
          Writes a constructor entry point.
 void logConstructorExit(java.lang.String constructorName)
          Writes a constructor exit point.
 void logData(java.lang.String entry)
          Writes a trace entry.
 void logData(java.lang.String dataName, byte[] dataValue)
          Writes a data value in hexadecimal.
 void logData(java.lang.String dataName, java.lang.String dataValue)
          Writes a data name-value pair.
 void logEntry(java.lang.String methodName)
          Writes a method entry point.
 void logEvent(java.lang.String event)
          Writes a trace event.
 void logExit(java.lang.String methodName)
          Writes a method exit point.
 void logParm(java.lang.String[] parmNameArray, java.lang.String[] parmValueArray)
          Writes the parameters of a method.
 void logParm(java.lang.String parmName, byte[] parmValue)
          Writes the parameters of a method.
 void logParm(java.lang.String parmName, java.lang.String parmValue)
          Writes the parameters of a method.
 void logParm(java.lang.String parm1Name, java.lang.String parm1Value, java.lang.String parm2Name, java.lang.String parm2Value)
          Writes the parameters of a method.
 void logParm(java.lang.String parm1Name, java.lang.String parm1Value, java.lang.String parm2Name, java.lang.String parm2Value, java.lang.String parm3Name, java.lang.String parm3Value)
          Writes the parameters of a method.
 void logResult(byte[] result)
          Writes the byte array result of a method.
 void logResult(java.lang.String result)
          Writes the result of a method.
protected  void openRootTag()
          Adds the opening root tag for this trace run.
protected  void prolog()
          Adds the XML prolog stating the XML version.
static void setOutputFile(java.lang.String outputFile)
          Creates an HFS file and sets it as the output stream for tracing.
static void setOutputWriter(java.io.PrintWriter outputWriter)
          Sets the output stream used for tracing to a print stream.
static void setTIDTracing(boolean on)
          Adds or removes the thread identifier to trace entries.
static void setTraceLevel(int traceLevel)
          Sets the current level of IMS Tracing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TRACE_EXCEPTIONS

public static final int TRACE_EXCEPTIONS
Causes tracing of Exception constructors

TRACE_CTOR1

public static final int TRACE_CTOR1
Causes tracing of level 1 constructors

TRACE_METHOD1

public static final int TRACE_METHOD1
Causes tracing of level 1 methods and constructors.

TRACE_DATA1

public static final int TRACE_DATA1
Causes tracing of level 1 parameters, return values, methods, and constructors.

TRACE_CTOR2

public static final int TRACE_CTOR2
Causes tracing of level 2 constructors and all level 1 entries.

TRACE_METHOD2

public static final int TRACE_METHOD2
Causes tracing of level 2 methods and constructors, and all level 1 entries.

TRACE_DATA2

public static final int TRACE_DATA2
Causes tracing of level 2 parameters, return values, methods, constructors, and all level 1 entries.

TRACE_CTOR3

public static final int TRACE_CTOR3
Causes tracing of level 3 constructors and all level 1 and level 2 entries.

TRACE_METHOD3

public static final int TRACE_METHOD3
Causes tracing of level 3 methods and constructors, and all level 1 and level 2 entries.

TRACE_DATA3

public static final int TRACE_DATA3
Causes tracing of level 3 parameters, return values, methods, constructors, and all level 1 and level 2 entries.

traceOn

public static boolean traceOn
Value indicating whether tracing is turned on or not.

libTraceLevel

public static int libTraceLevel
Trace level for code.

maxBinaryLength

protected static int maxBinaryLength

traceName

protected static java.lang.String traceName
Name of the Application being traced
Method Detail

enable

public static void enable()
Enables XML Tracing with default Name and TraceLevel

enable

public static void enable(java.lang.String name)
Enables XML Tracing with the default trace level, XMLTrace.TRACE_EXCEPTIONS
Parameters:
name - the root element of the xml file

enable

public static void enable(int level)
Enables XML Tracing with the default root element name, TracedApp.
Parameters:
level - The specified level of tracing

enable

public static void enable(java.lang.String name,
                          int level)
Enables XML Tracing with the specified root element and trace level.
Parameters:
name - the root element of the xml file
level - The specified level of tracing

currentTrace

public static XMLTrace currentTrace()
Returns the XMLTrace object for the current thread.

setTIDTracing

public static void setTIDTracing(boolean on)
Adds or removes the thread identifier to trace entries. This value must be set before any trace activity and before a call to XMLTrace.currentTrace(). It is recommended that this method be used within a static block of the main application class.
Parameters:
on - if true, adds the thread name to a trace entry, otherwise does not add the thread name.

setTraceLevel

public static void setTraceLevel(int traceLevel)
Sets the current level of IMS Tracing.
Parameters:
traceLevel - the current level of tracing

getTraceLevel

public static int getTraceLevel()
Returns the current level of IMS Tracing.

setOutputWriter

public static void setOutputWriter(java.io.PrintWriter outputWriter)
Sets the output stream used for tracing to a print stream. If neither a PrintWriter nor output file has been set, and tracing is enabled, the trace data is written to the System.err stream. To write to the System.err stream, call setOutputWriter(new PrintWriter(System.err)). To write to the System.out stream, call setOutputWriter(new PrintWriter(System.out)).
Parameters:
outputStream - A PrintStream for tracing.

setOutputFile

public static void setOutputFile(java.lang.String outputFile)
                          throws java.io.IOException
Creates an HFS file and sets it as the output stream for tracing. The application is responsible for closing the created output file by calling the XMLTrace.close() method when the trace is complete. Only one trace file can be open at a time; if XMLTrace.setOutputFile(...) is called when a file is already open, then the original file is automatically closed.
Parameters:
outputFile - The file name to create for logging
Throws:
java.io.IOException - If an I/O error occurs

prolog

protected void prolog()
Adds the XML prolog stating the XML version.

openRootTag

protected void openRootTag()
Adds the opening root tag for this trace run.

closeRootTag

protected static void closeRootTag()
Adds the closing root tag for this trace run.

close

public static void close()
Closes the trace file.

logConstructorEntry

public void logConstructorEntry(java.lang.String constructorName)
Writes a constructor entry point.
Parameters:
constructorName - The constructor being entered.

logConstructorExit

public void logConstructorExit(java.lang.String constructorName)
Writes a constructor exit point.
Parameters:
constructorName - The constructor being exited.

logEntry

public void logEntry(java.lang.String methodName)
Writes a method entry point.
Parameters:
methodName - The method being entered.

logExit

public void logExit(java.lang.String methodName)
Writes a method exit point.
Parameters:
methodName - The method being exited.

logResult

public void logResult(java.lang.String result)
Writes the result of a method.
Parameters:
result - The result to be written.

logResult

public void logResult(byte[] result)
Writes the byte array result of a method. This method adds XML tags for a result prior to writing the result to the log and it dumps the byte array as hex characters.
Parameters:
result - The result to be written in hexadecimal

logParm

public void logParm(java.lang.String parmName,
                    byte[] parmValue)
Writes the parameters of a method. This method adds XML tags for a parameter, and optionally the value of the parameter, prior to writing the parameter to the log.
Parameters:
parmName - the name of the parameter.
parmValue - the value.

logData

public void logData(java.lang.String dataName,
                    java.lang.String dataValue)
Writes a data name-value pair.
Parameters:
dataName - The name of the data to be written.
dataValue - The value of the data to be written.

logData

public void logData(java.lang.String dataName,
                    byte[] dataValue)
Writes a data value in hexadecimal.
Parameters:
dataName - The name of the data to be written.
dataValue - The value of the data to be written.

logData

public void logData(java.lang.String entry)
Writes a trace entry. If XMLTrace.traceOn is true and an output stream has been established, the trace data is written to that output stream. If traceOn is true and an output stream has not been established, the trace data is written to the System.err stream.
Parameters:
entry - The entry to write to the log.

logParm

public void logParm(java.lang.String parmName,
                    java.lang.String parmValue)
Writes the parameters of a method. This method adds XML tags for a parameter, and optionally the value of the parameter, prior to writing the parameter to the log.
Parameters:
parmName - The name of the parameter.
parmValue - The value of the parameter, or null.

logParm

public void logParm(java.lang.String parm1Name,
                    java.lang.String parm1Value,
                    java.lang.String parm2Name,
                    java.lang.String parm2Value)
Writes the parameters of a method. This method adds XML tags for two parameters, and optionally the value of these parameters, prior to writing them to the log.
Parameters:
parm1Name - The name of the first parameter.
parm1Value - The value of the first parameter, or null.
parm2Name - The name of the second parameter.
parm2Value - The value of the second parameter, or null.

logParm

public void logParm(java.lang.String parm1Name,
                    java.lang.String parm1Value,
                    java.lang.String parm2Name,
                    java.lang.String parm2Value,
                    java.lang.String parm3Name,
                    java.lang.String parm3Value)
Writes the parameters of a method. This method adds XML tags for three parameters, and optionally the value of these parameters, prior to writing them to the log.
Parameters:
parm1Name - The name of the first parameter.
parm1Value - The value of the first parameter, or null.
parm2Name - The name of the second parameter.
parm2Value - The value of the second parameter, or null.
parm3Name - The name of the third parameter.
parm3Value - The value of the third parameter, or null.

logParm

public void logParm(java.lang.String[] parmNameArray,
                    java.lang.String[] parmValueArray)
Writes the parameters of a method. This method adds XML tags for an array of parameter names, and optionally the value of these parameters, prior to writing them to the log.
Parameters:
parmArray - The array of parameter names.
parmValueArray - The array of values of the parameters, or null.

logEvent

public void logEvent(java.lang.String event)
Writes a trace event. A trace event can be any String value.
Parameters:
event - The event to be traced.


(C) International Business Machines Corporation 2004. All rights reserved.