|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.ims.rds.XMLTrace
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
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 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.
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 |
public static final int TRACE_EXCEPTIONS
public static final int TRACE_CTOR1
public static final int TRACE_METHOD1
public static final int TRACE_DATA1
public static final int TRACE_CTOR2
public static final int TRACE_METHOD2
public static final int TRACE_DATA2
public static final int TRACE_CTOR3
public static final int TRACE_METHOD3
public static final int TRACE_DATA3
public static boolean traceOn
public static int libTraceLevel
protected static int maxBinaryLength
protected static java.lang.String traceName
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 XMLTrace currentTrace()
public 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 void setTraceLevel(int traceLevel)
traceLevel
- the current level of tracingpublic static int getTraceLevel()
public static void setOutputWriter(java.io.PrintWriter outputWriter)
setOutputWriter(new PrintWriter(System.err))
.
To write to the System.out stream, call setOutputWriter(new PrintWriter(System.out))
.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 occursprotected void prolog()
protected void openRootTag()
protected static void closeRootTag()
public static void close()
public void logConstructorEntry(java.lang.String constructorName)
constructorName
- The constructor being entered.public void logConstructorExit(java.lang.String constructorName)
constructorName
- The constructor being exited.public void logEntry(java.lang.String methodName)
methodName
- The method being entered.public void logExit(java.lang.String methodName)
methodName
- The method being exited.public void logResult(java.lang.String result)
result
- The result to be written.public void logResult(byte[] result)
result
- The result to be written in hexadecimalpublic void logParm(java.lang.String parmName, byte[] parmValue)
parmName
- the name of the parameter.parmValue
- the value.public void logData(java.lang.String dataName, java.lang.String dataValue)
dataName
- The name of the data to be written.dataValue
- The value of the data to be written.public void logData(java.lang.String dataName, byte[] dataValue)
dataName
- The name of the data to be written.dataValue
- The value of the data to be written.public void logData(java.lang.String entry)
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.entry
- The entry to write to the log.public void logParm(java.lang.String parmName, java.lang.String parmValue)
parmName
- The name of the parameter.parmValue
- The value of the parameter, or null.public void logParm(java.lang.String parm1Name, java.lang.String parm1Value, java.lang.String parm2Name, java.lang.String parm2Value)
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.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)
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.public void logParm(java.lang.String[] parmNameArray, java.lang.String[] parmValueArray)
parmArray
- The array of parameter names.parmValueArray
- The array of values of the parameters, or null.public void logEvent(java.lang.String event)
event
- The event to be traced.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |