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:
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).


Variable Index

 o CONVERSION
Character set conversion trace category.
 o DATASTREAM
Data stream trace category.
 o DIAGNOSTIC
Diagnostic message trace category.
 o ERROR
Error message trace category.
 o INFORMATION
Information message trace category.
 o WARNING
Warning message trace category.

Method Index

 o getFileName()
Returns the trace file name.
 o getPrintWriter()
Returns the PrintWriter object.
 o isTraceConversionOn()
Indicates if character set conversion tracing is enabled.
 o isTraceDatastreamOn()
Indicates if data stream tracing is enabled.
 o isTraceDiagnosticOn()
Indicates if diagnostic tracing is enabled.
 o isTraceErrorOn()
Indicates if error tracing is enabled.
 o isTraceInformationOn()
Indicates if information tracing is enabled.
 o isTraceOn()
Indicates if overall tracing is enabled.
 o isTraceWarningOn()
Indicates if warning tracing is enabled.
 o log(int, String)
Logs a message in the specified category.
 o log(int, String, boolean)
Logs a message and a boolean value in the specified category.
 o log(int, String, byte[])
Logs a message and byte data in the specified category.
 o log(int, String, byte[], int, int)
Logs a message and byte data in the specified category.
 o log(int, String, int)
Logs a message and an integer value in the specified category.
 o log(int, String, Throwable)
Logs a message in the specified category.
 o setFileName(String)
Sets the trace file name.
 o setPrintWriter(PrintWriter)
Sets the PrintWriter object.
 o setTraceConversionOn(boolean)
Sets character set conversion tracing on or off.
 o setTraceDatastreamOn(boolean)
Sets data stream tracing on or off.
 o setTraceDiagnosticOn(boolean)
Sets diagnostic tracing on or off.
 o setTraceErrorOn(boolean)
Sets error tracing on or off.
 o setTraceInformationOn(boolean)
Sets information tracing on or off.
 o setTraceOn(boolean)
Sets tracing on or off.
 o setTraceWarningOn(boolean)
Sets warning tracing on or off.

Variables

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

 o DIAGNOSTIC
 public static final int DIAGNOSTIC
Diagnostic message trace category. This category is used to log object state information.

 o ERROR
 public static final int ERROR
Error message trace category. This category is used to log errors that cause an exception.

 o INFORMATION
 public static final int INFORMATION
Information message trace category. This category is used to track the flow of control through the code.

 o WARNING
 public static final int WARNING
Warning message trace category. This category is used to log errors that are recoverable.

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

Methods

 o 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.
 o getPrintWriter
 public static PrintWriter getPrintWriter()
Returns the PrintWriter object.

Returns:
The PrintWriter object for the trace data output.
 o isTraceConversionOn
 public static final boolean isTraceConversionOn()
Indicates if character set conversion tracing is enabled.

Returns:
true if conversions are traced; false otherwise.
 o isTraceDatastreamOn
 public static final boolean isTraceDatastreamOn()
Indicates if data stream tracing is enabled.

Returns:
true if data streams are traced; false otherwise.
 o isTraceDiagnosticOn
 public static final boolean isTraceDiagnosticOn()
Indicates if diagnostic tracing is enabled.

Returns:
true if diagnostic messages are traced; false otherwise.
 o isTraceErrorOn
 public static final boolean isTraceErrorOn()
Indicates if error tracing is enabled.

Returns:
true if error messages are traced; false otherwise.
 o isTraceInformationOn
 public static final boolean isTraceInformationOn()
Indicates if information tracing is enabled.

Returns:
true if information messages are traced; false otherwise.
 o 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.
 o isTraceWarningOn
 public static final boolean isTraceWarningOn()
Indicates if warning tracing is enabled.

Returns:
true if warning messages are traced; false otherwise.
 o 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].
message - The message to log.
 o 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].
message - The message to log.
e - The Throwable object that contains the stack trace to log.
 o 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].
message - The message to log.
value - The integer value to log.
 o 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].
message - The message to log.
value - The boolean data to log.
 o 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].
message - The message to log.
data - The bytes to log.
 o 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].
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.
 o 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
 o 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:
traceDatastream - If true, conversion tracing is on; otherwise, conversion tracing is off.
See Also:
setTraceOn
 o 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
 o 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
 o 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.
 o 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.
 o setTraceInformationOn
 public static void setTraceInformationOn(boolean traceInfo)
Sets information tracing on or off. The actual tracing does not happen unless tracing is on.

Parameters:
traceInfo - If true, information tracing is on; otherwise, information tracing is off.
See Also:
setTraceOn
 o 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.
 o 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