|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.ims.base.IMSTrace
IMSTrace provides tracing facilities to document the flow of control in an IMS Java application.
The static public variable IMSTrace.traceOn
determines whether tracing
is enabled or not. By default IMSTrace.traceOn
is set to false. If an
application wishes to utilize tracing, it should set this variable to true within a
static block of their IMSApplication
subclass.
The static public variable IMSTrace.libTraceLevel
determines the amount
of tracing that will occur within IMS provided packages. If libTraceLevel
is zero, no library tracing occurs. IMSTrace
defines three levels of three
types of tracing constants which are used within library provided code. These constants
represent progressively more tracing at each successive level. Generally, level 1 constants
are used for larger objects while level 3 constants are used for smaller objects or high volume
functions. The higher the value of IMSTrace.libTraceLevel
, the more
trace data will be written to the output stream. In addition, IMSTrace
defines the constant TRACE_EXCEPTIONS
. This level 0 constant is used to trace
the construction of library provided exceptions. The following
traceLevel
constants represent successively higher levels of tracing:
TRACE_EXCEPTIONS
TRACE_CTOR1
TRACE_METHOD1
TRACE_DATA1
TRACE_CTOR2
TRACE_METHOD2
TRACE_DATA2
TRACE_CTOR3
TRACE_METHOD3
TRACE_DATA3
By default, IMSTrace.libTraceLevel
is set to TRACE_EXCEPTIONS
. If
an application wishes to change the amount of tracing within the IMS library provided
packages, it should update this variable within a static block of their
IMSApplication
subclass.
An application can control the output location used for tracing by calling
IMSTrace.setOutputStream
with a valid print stream or by calling
IMSTrace.setOutputWriter
with a valid character output stream.
One of these function should be called within a static block of an
IMSApplication
subclass. For example, to use System.out
for trace output and set libTraceLevel
to TRACE_DATA2
:
public class MyApplication extends IMSApplication {
static {
IMSTrace.traceOn = true;
IMSTrace.setOutputStream(System.out);
IMSTrace.libTraceLevel=IMSTrace.TRACE_DATA2;
}
public abstract void doBegin() throws com.ibm.ims.base.IMSException {
...
}
} // end MyApplication
IMSTrace.logData
is the primary method for writing trace data. If either
IMSTrace.setOutputStream
or IMSTrace.setOutputWriter
was called with a valid output stream, and IMSTrace.traceOn
is set
to true, logData
writes its string data to this stream. If an error
occurs writing to one of these streams, or tracing is enabled and a stream has
not been provided, the trace data is written to the System.err stream. Prior to writing
its data to an output stream,
IMSTrace.logData
prepends a newline character and a number
of blank characters based on the current nested method level.
The IMS library provided packages utilize XML tags when logging its data. The following tags are used:
<entry>methodName</entry>
<exit>methodName</exit>
<parm></parm>
<parmName>parmName</parmName>
<parmChar>parmCharValue</parmChar>
<parmHex>parmHexValue</parmHex>
<data></data>
<dataName>dataName</dataName>
<dataChar>dataCharValue</dataChar>
<dataHex>dataHexValue</dataHex>
<result></result>
<resultChar>resultCharValue</resultChar>
<resultHex>resultHexValue</resultHex>
<event>eventValue</event>
As a convenience, IMSTrace
contains logging methods that add some of the
appropriate XML tags prior to writing the data to the log. These include:
logEntry
<entry>
tagslogExit
<exit>
tagslogParm
<parm>
, <parmName>
,
<parmChar>
, <parmHex> tags
logData
<data>
, <dataName>
,
<dataChar>
, <dataHex> tags
logResult
<result>
,
<resultChar>
, <resultHex> tags
logEvent
<event>
tags
To write to the IMSTrace, you need to get an IMSTrace object by calling the method
IMSTrace.currentTrace
. For example:
IMSTrace.currentTrace().logData("dataName", "dataValue");
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 |
encoding
|
protected java.lang.String |
formattedTID
|
protected int |
indentLevel
|
static int |
libTraceLevel
The trace level for IMS Library code. |
protected static int |
maxBinaryLength
|
protected static java.io.PrintStream |
outputStream
An optional byte output stream provided by the application. |
protected static java.io.Writer |
outputWriter
An optional character output stream provided by the application. |
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.util.Hashtable |
traceList
|
static boolean |
traceOn
The flag to indicate whether tracing is enabled. |
protected static boolean |
traceTID
|
protected static boolean |
xmlTrace
|
Constructor Summary | |
protected |
IMSTrace()
|
Method Summary | |
protected static java.lang.String |
byteArrayToHexString(byte[] array,
int offset,
int length)
|
static void |
closeOutputFile()
Closes the output file created by calling the createOutputFile. |
static void |
createOutputFile(java.lang.String outputFile)
Creates a log file and sets it as the output writer for tracing. |
static IMSTrace |
currentTrace()
Returns the IMSTrace object for the current thread. |
static IMSTrace |
getCurrentTrace()
This method is only for internal use. |
static int |
getMaxBinaryLength()
Returns the maximum length when tracing binary data (e.g. |
static java.io.PrintStream |
getOutputStream()
Returns the print stream used for tracing or null if a print stream has not been set. |
static java.io.Writer |
getOutputWriter()
Returns the character output stream used for tracing or null if a character output stream has not been set. |
protected void |
indent(java.lang.StringBuffer output)
Indents a StringBuffer appropriately. |
protected static void |
log(java.lang.String outputString)
Writes to the trace outputStream. |
void |
logConstructorEntry(int level,
java.lang.String constructorName)
Writes a constructor entry point if min tracing level is met. |
void |
logConstructorEntry(java.lang.String constructorName)
Deprecated. |
void |
logConstructorExit(int level,
java.lang.String constructorName)
Writes a constructor exit point if min tracing level is met. |
void |
logConstructorExit(java.lang.String constructorName)
Deprecated. |
void |
logData(int level,
java.lang.String dataName,
byte[] dataValue)
Writes a data value in binary and character. |
void |
logData(int level,
java.lang.String dataName,
java.lang.String dataValue)
Writes a data name-value pair. |
void |
logData(java.lang.String entry)
Writes a trace entry. |
void |
logData(java.lang.String dataName,
byte[] dataValue)
Deprecated. |
void |
logData(java.lang.String dataName,
java.lang.String dataValue)
Deprecated. |
void |
logEntry(int level,
java.lang.String methodName)
Writes a method entry point if min tracing level is met. |
void |
logEntry(java.lang.String methodName)
Deprecated. |
void |
logEvent(int level,
java.lang.String event)
Writes a trace event. |
void |
logEvent(java.lang.String event)
Deprecated. |
void |
logException(int level,
java.lang.Exception e)
Writes an Exception Stack Trace. |
void |
logException(int level,
java.lang.Throwable t)
Writes a Throwable Stack Trace. |
void |
logExit(int level,
java.lang.String methodName)
Writes a method exit point if min tracing level is met. |
void |
logExit(java.lang.String methodName)
Deprecated. |
void |
logParm(int level,
java.lang.String[] parmNameArray,
java.lang.String[] parmValueArray)
Writes the parameters of a method. |
void |
logParm(int level,
java.lang.String parmName,
boolean parmValue)
Writes the parameters of a method. |
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 |
logParm(int level,
java.lang.String parm1Name,
java.lang.String parm1Value,
java.lang.String parm2Name,
java.lang.String parm2Value)
Writes the parameters of a method. |
void |
logParm(int level,
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 |
logParm(java.lang.String[] parmNameArray,
java.lang.String[] parmValueArray)
Deprecated. |
void |
logParm(java.lang.String parmName,
byte[] parmValue)
Deprecated. |
void |
logParm(java.lang.String parmName,
java.lang.String parmValue)
Deprecated. |
void |
logParm(java.lang.String parm1Name,
java.lang.String parm1Value,
java.lang.String parm2Name,
java.lang.String parm2Value)
Deprecated. |
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)
Deprecated. |
void |
logResult(byte[] result)
Deprecated. |
void |
logResult(int level,
boolean result)
Writes the result 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. |
void |
logResult(java.lang.String result)
Deprecated. |
void |
logVersion()
Deprecated. Replaced by IMSJavaVersionInfo.logVersion(IMSTrace) |
static void |
setCurrentTrace(IMSTrace traceObject)
This method is only for internal use. |
static void |
setMaxBinaryLength(int maxBinaryLength)
Sets the maximum length when tracing binary data. |
static void |
setOutputStream(java.io.PrintStream outputStream)
Sets the output stream used for tracing to a print stream. |
static void |
setOutputWriter(java.io.Writer outputStream)
Sets the output stream used for tracing to a character output stream. |
static void |
setTIDTracing(boolean on)
Adds or removes the thread identifier to trace entries. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static boolean traceOn
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 int libTraceLevel
protected static java.io.PrintStream outputStream
protected static java.io.Writer outputWriter
protected static java.util.Hashtable traceList
protected java.lang.String formattedTID
protected static boolean traceTID
protected int indentLevel
protected static int maxBinaryLength
protected static boolean xmlTrace
protected static java.lang.String encoding
Constructor Detail |
protected IMSTrace()
Method Detail |
public static IMSTrace currentTrace()
public static void setCurrentTrace(IMSTrace traceObject)
public static IMSTrace getCurrentTrace()
public static void setOutputStream(java.io.PrintStream outputStream)
outputStream
- A PringStream for tracing.public static void setOutputWriter(java.io.Writer outputStream)
outputStream
- An output stream for tracing.public static void createOutputFile(java.lang.String outputFile) throws java.io.IOException
outputFile
- The file name to create for loggingjava.io.IOException
- If an I/O error occurspublic static void closeOutputFile() throws java.io.IOException
java.io.IOException
- If an I/O error occurspublic static java.io.PrintStream getOutputStream()
setOutputWriter
. If neither a character output stream
nor a print stream has been set, and tracing is enabled, the trace data
is written to the System.err stream.public static java.io.Writer getOutputWriter()
setOutputStream
. If neither a character output stream
nor a print stream has been set, and tracing is enabled, the trace data
is written to the System.err stream.public static void setMaxBinaryLength(int maxBinaryLength)
maxBinaryLength
- the maximum length traced for binary data.public static int getMaxBinaryLength()
public static void setTIDTracing(boolean on)
IMSTrace.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 void logData(java.lang.String entry)
IMSTrace.traceOn
is true
and an
output stream has been established, the trace data is written to that output stream.
The output stream can be either a print stream, set by calling
setOutputStream
, or a character output stream, set by calling
setOutputWriter
. 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.protected void indent(java.lang.StringBuffer output)
protected static void log(java.lang.String outputString)
public void logEntry(int level, java.lang.String methodName)
level
- minimun tracing level required.methodName
- The method being entered.public void logExit(int level, java.lang.String methodName)
level
- minimun tracing level required.methodName
- The method being exited.public void logConstructorEntry(int level, java.lang.String constructorName)
level
- minimun tracing level required.constructorName
- The constructor being entered.public void logConstructorExit(int level, java.lang.String constructorName)
level
- minimun tracing level required.constructorName
- The constructor being exited.public void logException(int level, java.lang.Exception e)
level
- minimun tracing level required.e
- The Exception to log.public void logException(int level, java.lang.Throwable t)
level
- minimun tracing level required.e
- The Exception to log.public void logResult(int level, boolean result)
level
- minimun tracing level required.result
- The result to be written.public void logResult(int level, java.lang.String result)
level
- minimun tracing level required.result
- The result to be written.public void logResult(int level, byte[] result)
level
- minimun tracing level required.result
- The result to be written in hexadecimalpublic void logParm(int level, java.lang.String parmName, byte[] parmValue)
level
- minimun tracing level required.parmName
- The name of the parameter.parmValue
- The value of the parameter, or null.public void logData(int level, java.lang.String dataName, java.lang.String dataValue)
level
- minimun tracing level required.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)
level
- minimun tracing level required.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)
level
- minimun tracing level required.parmName
- The name of the parameter.parmValue
- The value of the parameter, or null.public void logParm(int level, java.lang.String parmName, boolean parmValue)
level
- minimun tracing level required.parmName
- The name of the first parameter.parmValue
- The boolean value of the first parameter.public void logParm(int level, java.lang.String parm1Name, java.lang.String parm1Value, java.lang.String parm2Name, java.lang.String parm2Value)
level
- minimun tracing level required.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(int level, java.lang.String parm1Name, java.lang.String parm1Value, java.lang.String parm2Name, java.lang.String parm2Value, java.lang.String parm3Name, java.lang.String parm3Value)
level
- minimun tracing level required.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(int level, java.lang.String[] parmNameArray, java.lang.String[] parmValueArray)
level
- minimun tracing level required.parmArray
- The array of parameter names.parmValueArray
- The array of values of the parameters, or null.public void logEvent(int level, java.lang.String event)
level
- minimun tracing level required.event
- The event to be traced.protected static java.lang.String byteArrayToHexString(byte[] array, int offset, int length)
public void logVersion()
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 logConstructorEntry(java.lang.String constructorName)
constructorName
- The constructor being entered.public void logConstructorExit(java.lang.String constructorName)
constructorName
- The constructor 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 of the parameter, or null.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 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 |