com.ibm.ims.base
Class XMLTrace

java.lang.Object
  |
  +--com.ibm.ims.base.IMSTrace
        |
        +--com.ibm.ims.base.XMLTrace
Direct Known Subclasses:
J2EETrace

public class XMLTrace
extends IMSTrace

XMLTrace provides tracing facilities to document the flow of control in an IMS Java application. XMLTrace extends the interface of IMSTrace offering an XML tagged version of the IMS Tracing facility.

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 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 IMSTrace 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.


Field Summary
protected static java.lang.String traceName
          Name of the Application being traced
protected  java.util.Stack traceStack
           
 
Fields inherited from class com.ibm.ims.base.IMSTrace
encoding, formattedTID, indentLevel, libTraceLevel, maxBinaryLength, outputStream, outputWriter, TRACE_CTOR1, TRACE_CTOR2, TRACE_CTOR3, TRACE_DATA1, TRACE_DATA2, TRACE_DATA3, TRACE_EXCEPTIONS, TRACE_METHOD1, TRACE_METHOD2, TRACE_METHOD3, traceList, traceOn, traceTID, xmlTrace
 
Constructor Summary
protected XMLTrace()
           
 
Method Summary
static void close()
          Closes the trace file.
protected  void closeDocument()
          Closes all open tags including the root.
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.
protected  java.lang.String fixString(java.lang.String input)
          Fixes a string by replacing XML reserved characters.
static int getTraceLevel()
          Returns the current level of IMS Tracing.
 void logConstructorEntry(int level, java.lang.String constructorName)
          Writes a constructor entry point.
 void logConstructorExit(int level, java.lang.String constructorName)
          Writes a constructor exit point.
 void logData(int level, java.lang.String dataName, byte[] dataValue)
          Writes a data value in hexadecimal.
 void logData(int level, java.lang.String dataName, java.lang.String dataValue)
          Writes a data name-value pair.
 void logEntry(int level, java.lang.String methodName)
          Writes a method entry point.
 void logEvent(int level, java.lang.String event)
          Writes a trace event.
 void logException(int level, java.lang.Exception e)
          Writes an Exception Stack Trace.
 void logException(int level, java.lang.Throwable e)
          Writes an Exception Stack Trace.
 void logExit(int level, java.lang.String methodName)
          Writes a method exit point.
 void logParm(int level, java.lang.String parmName, byte[] parmValue)
          Writes the parameters of a method.
 void logParm(int level, java.lang.String parmName, java.lang.String parmValue)
          Writes the parameters of a method.
 void logResult(int level, byte[] result)
          Writes the byte array result of a method.
 void logResult(int level, java.lang.String result)
          Writes the result of a method.
protected  void openDocument()
          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 setOutputFile(java.lang.String outputFile, java.lang.String encoding)
          Creates a log file and sets it as the output writer for tracing.
static void setOutputStream(java.io.PrintStream outputStream)
          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.
 
Methods inherited from class com.ibm.ims.base.IMSTrace
byteArrayToHexString, closeOutputFile, createOutputFile, currentTrace, getCurrentTrace, getMaxBinaryLength, getOutputStream, getOutputWriter, indent, log, logConstructorEntry, logConstructorExit, logData, logData, logData, logEntry, logEvent, logExit, logParm, logParm, logParm, logParm, logParm, logParm, logParm, logParm, logParm, logResult, logResult, logResult, logVersion, setCurrentTrace, setMaxBinaryLength, setOutputWriter
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

traceStack

protected java.util.Stack traceStack

traceName

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

XMLTrace

protected XMLTrace()
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

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.

getTraceLevel

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

setOutputStream

public static void setOutputStream(java.io.PrintStream outputStream)
Sets the output stream used for tracing to a print stream. If neither a character output stream nor print stream has been set, and tracing is enabled, the trace data is written to the System.err stream.
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

setOutputFile

public static void setOutputFile(java.lang.String outputFile,
                                 java.lang.String encoding)
                          throws java.io.IOException
Creates a log file and sets it as the output writer for tracing. Data will be written to the file according to the specified character encoding. Calling getOutputStream will return a reference to the newly created PrintStream. The application is responsible for closing the created output file by calling XMLTrace.close(). Since the IMS Java code creates the PrintStream it does not generate a ResetTraceEvent. 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
encoding - The name of a supported character encoding
Throws:
java.io.IOException - If an I/O error occurs

prolog

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

openDocument

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

closeDocument

protected void closeDocument()
Closes all open tags including the root.

close

public static void close()
Closes the trace file. Closes all open tags.

logConstructorEntry

public void logConstructorEntry(int level,
                                java.lang.String constructorName)
Writes a constructor entry point.
Overrides:
logConstructorEntry in class IMSTrace
Parameters:
constructorName - The constructor being entered.

logConstructorExit

public void logConstructorExit(int level,
                               java.lang.String constructorName)
Writes a constructor exit point.
Overrides:
logConstructorExit in class IMSTrace
Parameters:
constructorName - The constructor being exited.

logEntry

public void logEntry(int level,
                     java.lang.String methodName)
Writes a method entry point.
Overrides:
logEntry in class IMSTrace
Parameters:
methodName - The method being entered.

logExit

public void logExit(int level,
                    java.lang.String methodName)
Writes a method exit point.
Overrides:
logExit in class IMSTrace
Parameters:
methodName - The method being exited.

logException

public void logException(int level,
                         java.lang.Exception e)
Writes an Exception Stack Trace. Tags and formats the printStackTrace information. Since this method does not guarantee output format any unexpected formatting results in the entire printStackTrace output being logged.
Overrides:
logException in class IMSTrace
Parameters:
e - The Exception to log.

logException

public void logException(int level,
                         java.lang.Throwable e)
Writes an Exception Stack Trace. Tags and formats the printStackTrace information. Since this method does not guarantee output format any unexpected formatting results in the entire printStackTrace output being logged.
Overrides:
logException in class IMSTrace
Parameters:
e - The Exception to log.

logResult

public void logResult(int level,
                      java.lang.String result)
Writes the result of a method.
Overrides:
logResult in class IMSTrace
Parameters:
result - The result to be written.

logResult

public void logResult(int level,
                      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.
Overrides:
logResult in class IMSTrace
Parameters:
result - The result to be written in hexadecimal

logParm

public void logParm(int level,
                    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.
Overrides:
logParm in class IMSTrace
Parameters:
parmName - the name of the parameter.
parmValue - the value.

logData

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

logData

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

logParm

public void logParm(int level,
                    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.
Overrides:
logParm in class IMSTrace
Parameters:
parmName - The name of the parameter.
parmValue - The value of the parameter, or null.

logEvent

public void logEvent(int level,
                     java.lang.String event)
Writes a trace event. A trace event can be any String value.
Overrides:
logEvent in class IMSTrace
Parameters:
event - The event to be traced.

fixString

protected java.lang.String fixString(java.lang.String input)
Fixes a string by replacing XML reserved characters.


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