All Packages Class Hierarchy This Package Previous Next Index
Class com.ibm.as400.access.Trace
java.lang.Object
|
+----com.ibm.as400.access.Trace
- public class Trace
- extends Object
The Trace class logs trace points and diagnostic messages. Each trace point and diagnostic message is logged by category. The valid categories are:
- DATASTREAM
This category is used by JT/400 classes to log data flow between the local host and the remote system. It is not intended for use by classes that use JT/400 classes.
- DIAGNOSTIC
This category is used to log object state information.
- ERROR
This category is used to log errors that cause an exception.
- INFORMATION
This category is used to track the flow of control through the code.
- WARNING
This category is used to log errors that are recoverable.
- CONVERSION
This category is used by JT/400 classes to log character set conversions between Unicode and native code pages. It is not intended for use by classes that use JT/400 classes.
- PROXY
This category is used by JT/400 classes to log data flow between the client and the proxy server. It is not intended for use by classes that use JT/400 classes.
- THREAD
This category is used to enable or disable tracing of thread information. This is useful when debugging multi-threaded applications. Trace information can not be directly logged to this category.
- ALL
This category is used to enable or disable tracing for all of the above categories at once. Trace information can not be directly logged to this category.
The caller can enable or disable all tracing or specific trace categories. Enabling or disabling one category does not affect other categories.
// tracing is off by default
..
Trace.setTraceErrorOn(true); // error messages enabled
Trace.setTraceWarningOn(true); // warning messages enabled
Trace.setTraceOn(true); // error and warning tracing enabled
..
Trace.setTraceOn(false); // all tracing disabled
..
Trace.setTraceOn(true); // error and warning tracing enabled
..
Trace.setTraceInformationOn(true); // trace info. messages enabled
..
Trace.setTraceWarningOn(false); // warning messages disabled
The traces are logged to standard out by default. A file name can be provided to log to a file. File logging is only possible in an application as most browsers do not allow access to the local file system.
Two techniques for logging traces are as follows:
..
// Let the log method determine if logging should occur
Trace.log(Trace.INFORMATION, "I got here...");
..
// Pre-determine if we should log. This may be more efficient
// if you are collecting data to log.
if (Trace.isTraceOn() && Trace.isTraceInformationOn())
{
Trace.log(Trace.INFORMATION, "I got here...");
}
It is suggested that programs provide some mechanism to enable tracing at run-time, so
that the modification and recompilation of code is not necessary. Two possibilities
for that mechanism are a command line argument (for applications) or a menu option
(for applications and applets).
In addition, tracing can be set using the "com.ibm.as400.access.Trace.category"
and "com.ibm.as400.access.Trace.file" system properties.
-
ALL
- All trace category.
-
CONVERSION
- Character set conversion trace category.
-
DATASTREAM
- Data stream trace category.
-
DIAGNOSTIC
- Diagnostic message trace category.
-
ERROR
- Error message trace category.
-
INFORMATION
- Information message trace category.
-
PROXY
- Proxy trace category.
-
THREAD
- Thread trace category.
-
WARNING
- Warning message trace category.
-
getFileName()
- Returns the trace file name.
-
getPrintWriter()
- Returns the PrintWriter object.
-
isTraceAllOn()
- Indicates if all of the tracing categories are enabled.
-
isTraceConversionOn()
- Indicates if character set conversion tracing is enabled.
-
isTraceDatastreamOn()
- Indicates if data stream tracing is enabled.
-
isTraceDiagnosticOn()
- Indicates if diagnostic tracing is enabled.
-
isTraceErrorOn()
- Indicates if error tracing is enabled.
-
isTraceInformationOn()
- Indicates if information tracing is enabled.
-
isTraceOn()
- Indicates if overall tracing is enabled.
-
isTraceProxyOn()
- Indicates if proxy tracing is enabled.
-
isTraceThreadOn()
- Indicates if thread tracing is enabled.
-
isTraceWarningOn()
- Indicates if warning tracing is enabled.
-
log(int, String)
- Logs a message in the specified category.
-
log(int, String, boolean)
- Logs a message and a boolean value in the specified category.
-
log(int, String, byte[])
- Logs a message and byte data in the specified category.
-
log(int, String, byte[], int, int)
- Logs a message and byte data in the specified category.
-
log(int, String, int)
- Logs a message and an integer value in the specified category.
-
log(int, String, Throwable)
- Logs a message in the specified category.
-
log(int, Throwable)
- Logs a message in the specified category.
-
setFileName(String)
- Sets the trace file name.
-
setPrintWriter(PrintWriter)
- Sets the PrintWriter object.
-
setTraceAllOn(boolean)
- Sets tracing for all categories on or off.
-
setTraceConversionOn(boolean)
- Sets character set conversion tracing on or off.
-
setTraceDatastreamOn(boolean)
- Sets data stream tracing on or off.
-
setTraceDiagnosticOn(boolean)
- Sets diagnostic tracing on or off.
-
setTraceErrorOn(boolean)
- Sets error tracing on or off.
-
setTraceInformationOn(boolean)
- Sets information tracing on or off.
-
setTraceOn(boolean)
- Sets tracing on or off.
-
setTraceProxyOn(boolean)
- Sets proxy stream tracing on or off.
-
setTraceThreadOn(boolean)
- Sets thread tracing on or off.
-
setTraceWarningOn(boolean)
- Sets warning tracing on or off.
DATASTREAM
public static final int DATASTREAM
- Data stream trace category. This category is used by JT/400 classes to log data flow between the local host and the remote system. It is not intended for use by classes that use JT/400 classes.
DIAGNOSTIC
public static final int DIAGNOSTIC
- Diagnostic message trace category. This category is used to log object state information.
ERROR
public static final int ERROR
- Error message trace category. This category is used to log errors that cause an exception.
INFORMATION
public static final int INFORMATION
- Information message trace category. This category is used to track the flow of control through the code.
WARNING
public static final int WARNING
- Warning message trace category. This category is used to log errors that are recoverable.
CONVERSION
public static final int CONVERSION
- Character set conversion trace category. This category is used by JT/400 classes to log conversions between Unicode and native code pages. It is not intended for use by classes that use JT/400 classes.
PROXY
public static final int PROXY
- Proxy trace category. This category is used by JT/400 classes to log data flow between the client and the proxy server. It is not intended for use by classes that use JT/400 classes.
THREAD
public static final int THREAD
- Thread trace category. This category is used to enable or disable tracing of thread information. This is useful when debugging multi-threaded applications. Trace information can not be directly logged to this category.
ALL
public static final int ALL
- All trace category. This category is used to enable or disable tracing for all of the other categories at once. Trace information can not be directly logged to this category.
getFileName
public static String getFileName()
- Returns the trace file name.
- Returns:
- The file name if logging to file. If logging to System.out, null is returned.
getPrintWriter
public static PrintWriter getPrintWriter()
- Returns the PrintWriter object.
- Returns:
- The PrintWriter object for the trace data output.
isTraceAllOn
public static final boolean isTraceAllOn()
- Indicates if all of the tracing categories are enabled.
- Returns:
- true if all categories are traced; false otherwise.
isTraceConversionOn
public static final boolean isTraceConversionOn()
- Indicates if character set conversion tracing is enabled.
- Returns:
- true if conversions are traced; false otherwise.
isTraceDatastreamOn
public static final boolean isTraceDatastreamOn()
- Indicates if data stream tracing is enabled.
- Returns:
- true if data streams are traced; false otherwise.
isTraceDiagnosticOn
public static final boolean isTraceDiagnosticOn()
- Indicates if diagnostic tracing is enabled.
- Returns:
- true if diagnostic messages are traced; false otherwise.
isTraceErrorOn
public static final boolean isTraceErrorOn()
- Indicates if error tracing is enabled.
- Returns:
- true if error messages are traced; false otherwise.
isTraceInformationOn
public static final boolean isTraceInformationOn()
- Indicates if information tracing is enabled.
- Returns:
- true if information messages are traced; false otherwise.
isTraceOn
public static final boolean isTraceOn()
- Indicates if overall tracing is enabled. If this is false, no tracing occurs.
- Returns:
- true if tracing is enabled; false otherwise.
isTraceProxyOn
public static final boolean isTraceProxyOn()
- Indicates if proxy tracing is enabled.
- Returns:
- true if proxy tracing is enabled; false otherwise.
isTraceThreadOn
public static final boolean isTraceThreadOn()
- Indicates if thread tracing is enabled.
- Returns:
- true if thread tracing is enabled; false otherwise.
isTraceWarningOn
public static final boolean isTraceWarningOn()
- Indicates if warning tracing is enabled.
- Returns:
- true if warning messages are traced; false otherwise.
log
public static final void log(int category,
String message)
- Logs a message in the specified category. If the category is disabled, nothing is logged.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
log
public static final void log(int category,
String message,
Throwable e)
- Logs a message in the specified category. If the category is disabled, nothing is logged.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
- e - The Throwable object that contains the stack trace to log.
log
public static final void log(int category,
Throwable e)
- Logs a message in the specified category. If the category is disabled, nothing is logged.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- e - The Throwable object that contains the stack trace to log.
log
public static final void log(int category,
String message,
int value)
- Logs a message and an integer value in the specified category. If the category is disabled, nothing is logged. The integer value is appended to the end of the message, preceded by two blanks.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
- value - The integer value to log.
log
public static final void log(int category,
String message,
boolean value)
- Logs a message and a boolean value in the specified category. If the category is disabled, nothing is logged. The boolean value is appended to the end of the message, preceded by two blanks. true is logged for true, and false is logged for false.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
- value - The boolean data to log.
log
public static final void log(int category,
String message,
byte data[])
- Logs a message and byte data in the specified category. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
- data - The bytes to log.
log
public static final void log(int category,
String message,
byte data[],
int offset,
int length)
- Logs a message and byte data in the specified category. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.
- Parameters:
- category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY].
- message - The message to log.
- data - The bytes to log.
- offset - The start offset in the data.
- length - The number of bytes of data to log.
setTraceAllOn
public static void setTraceAllOn(boolean traceAll)
- Sets tracing for all categories on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceAll - If true, tracing for each category is on; otherwise, tracing for each category is off.
- See Also:
- setTraceOn
setTraceConversionOn
public static void setTraceConversionOn(boolean traceConversion)
- Sets character set conversion tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceConversion - If true, conversion tracing is on; otherwise, conversion tracing is off.
- See Also:
- setTraceOn
setTraceDatastreamOn
public static void setTraceDatastreamOn(boolean traceDatastream)
- Sets data stream tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceDatastream - If true, data stream tracing is on; otherwise, data stream tracing is off.
- See Also:
- setTraceOn
setTraceDiagnosticOn
public static void setTraceDiagnosticOn(boolean traceDiagnostic)
- Sets diagnostic tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceDiagnostic - If true, diagnostic tracing is on; otherwise, diagnostic tracing is off.
- See Also:
- setTraceOn
setTraceErrorOn
public static void setTraceErrorOn(boolean traceError)
- Sets error tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceError - If true, error tracing is on; otherwise, error tracing is off.
- See Also:
- setTraceOn
setFileName
public static synchronized void setFileName(String fileName) throws IOException
- Sets the trace file name. If the file exists, output is appended to it. If the file does not exist, it is created.
- Parameters:
- fileName - The log file name. If this is null, output goes to System.out.
- Throws: IOException
- If an error occurs while accessing the file.
setPrintWriter
public static synchronized void setPrintWriter(PrintWriter obj) throws IOException
- Sets the PrintWriter object. All further trace output is sent to it.
- Parameters:
- obj - The PrintWriter object. If this is null, output goes to System.out.
- Throws: IOException
- If an error occurs while accessing the file.
setTraceInformationOn
public static void setTraceInformationOn(boolean traceInformation)
- Sets information tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceInformation - If true, information tracing is on; otherwise, information tracing is off.
- See Also:
- setTraceOn
setTraceOn
public static void setTraceOn(boolean traceOn)
- Sets tracing on or off. When this is off nothing is logged in any category, even those that are on. When this is on, tracing occurs for all categories that are also on.
- Parameters:
- traceOn - If true, tracing is on; otherwise, all tracing is disabled.
setTraceProxyOn
public static void setTraceProxyOn(boolean traceProxy)
- Sets proxy stream tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceProxy - If true, proxy tracing is on; otherwise, proxy tracing is off.
- See Also:
- setTraceOn
setTraceThreadOn
public static void setTraceThreadOn(boolean traceThread)
- Sets thread tracing on or off. The actual tracing does not happen unless tracing is on.
- Parameters:
- traceError - If true, thread tracing is on; otherwise, thread tracing is off.
- See Also:
- setTraceOn
setTraceWarningOn
public static void setTraceWarningOn(boolean traceWarning)
- Sets warning tracing on or off. The actual tracing does not happen unless tracing is enabled.
- Parameters:
- traceWarning - If true, warning tracing is enabled; otherwise, warning tracing is disabled.
- See Also:
- setTraceOn
All Packages Class Hierarchy This Package Previous Next Index