|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.ims.base.IMSTrace | +--com.ibm.ims.base.XMLTrace
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
TRACE_CTOR1
TRACE_METHOD1
TRACE_DATA1
TRACE_CTOR2
TRACE_METHOD2
TRACE_DATA2
TRACE_CTOR3
TRACE_METHOD3
TRACE_DATA3
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 |
protected java.util.Stack traceStack
protected static java.lang.String traceName
Constructor Detail |
protected XMLTrace()
Method Detail |
public static void enable()
public static void enable(java.lang.String name)
XMLTrace.TRACE_EXCEPTIONS
name
- the root element of the xml filepublic static void enable(int level)
level
- The specified level of tracingpublic static void enable(java.lang.String name, int level)
name
- the root element of the xml filelevel
- The specified level of tracingpublic static void setTIDTracing(boolean on)
XMLTrace.currentTrace()
. It is recommended that this method be
used within a static block of the main application class.on
- if true, adds the thread name to a trace entry, otherwise does not
add the thread name.public static int getTraceLevel()
public static void setOutputStream(java.io.PrintStream outputStream)
outputStream
- A PrintStream for tracing.public static void setOutputFile(java.lang.String outputFile) throws java.io.IOException
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.outputFile
- The file name to create for loggingjava.io.IOException
- If an I/O error occurspublic static void setOutputFile(java.lang.String outputFile, java.lang.String encoding) throws java.io.IOException
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.outputFile
- The file name to create for loggingencoding
- The name of a supported character encodingjava.io.IOException
- If an I/O error occursprotected void prolog()
protected void openDocument()
protected void closeDocument()
public static void close()
public void logConstructorEntry(int level, java.lang.String constructorName)
logConstructorEntry
in class IMSTrace
constructorName
- The constructor being entered.public void logConstructorExit(int level, java.lang.String constructorName)
logConstructorExit
in class IMSTrace
constructorName
- The constructor being exited.public void logEntry(int level, java.lang.String methodName)
logEntry
in class IMSTrace
methodName
- The method being entered.public void logExit(int level, java.lang.String methodName)
logExit
in class IMSTrace
methodName
- The method being exited.public void logException(int level, java.lang.Exception e)
logException
in class IMSTrace
e
- The Exception to log.public void logException(int level, java.lang.Throwable e)
logException
in class IMSTrace
e
- The Exception to log.public void logResult(int level, java.lang.String result)
logResult
in class IMSTrace
result
- The result to be written.public void logResult(int level, byte[] result)
logResult
in class IMSTrace
result
- The result to be written in hexadecimalpublic void logParm(int level, java.lang.String parmName, byte[] parmValue)
logParm
in class IMSTrace
parmName
- the name of the parameter.parmValue
- the value.public void logData(int level, java.lang.String dataName, java.lang.String dataValue)
logData
in class IMSTrace
dataName
- The name of the data to be written.dataValue
- The value of the data to be written.public void logData(int level, java.lang.String dataName, byte[] dataValue)
logData
in class IMSTrace
dataName
- The name of the data to be written.dataValue
- The value of the data to be written.public void logParm(int level, java.lang.String parmName, java.lang.String parmValue)
logParm
in class IMSTrace
parmName
- The name of the parameter.parmValue
- The value of the parameter, or null.public void logEvent(int level, java.lang.String event)
logEvent
in class IMSTrace
event
- The event to be traced.protected java.lang.String fixString(java.lang.String input)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |