com.ibm.as400.access
Class Trace

java.lang.Object
  extended bycom.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. Once appropriate category traces are enabled, trace must be turned on to get trace data. For example,

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.

Trace data can also be specified by component. Trace data is always written to the default log but component tracing provides a way to write trace data to a separate log.

The following example logs data for Function123 into log file c:\Function123.log, and logs data for Function456 into log file c:\Function456.log. Data for these two components is also traced to the normal trace file (standard output in this case since that is the default for normal tracing). The result is three sets of data -- a file containing trace data for only Function123, a file containing trace data for only Function456, and standard output which records all trace data. In the example a Java String object is used to indicate the component, but any object can be used.

Component tracing provides an easy way to write application specific trace data to a log or standard output. Any application and the Toolbox classes can use trace to log messages. With component tracing, application data can be easily separated from other data. For example,

Two techniques can be used to log information:

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.

Note: This class can exploit a standard Java Logger if one is defined in the JVM (per JSR 47, package java.util.logging, added in J2SE 1.4). See LOGGER_NAME.


Field Summary
static int CONVERSION
          'Character set conversion' trace category.
static int DATASTREAM
          'Data stream' trace category.
static int DIAGNOSTIC
          'Diagnostic message' trace category.
static int ERROR
          'Error message' trace category.
static int INFORMATION
          'Information message' trace category.
static int JDBC
          'JDBC' trace category.
static String LOGGER_NAME
          Name of the instance of java.util.logging.Logger that the Toolbox uses.
static int PCML
          'PCML' trace category.
static int PROXY
          'Proxy' trace category.
static int WARNING
          'Warning message' trace category.
 
Method Summary
static String getFileName()
          Returns the trace file name.
static String getFileName(Object component)
          Returns the trace file name for the specified component.
static PrintWriter getPrintWriter()
          Returns the PrintWriter object.
static PrintWriter getPrintWriter(Object component)
          Returns the print writer object for the specified component.
static boolean isTraceAllOn()
          Indicates if all of the tracing categories are enabled.
static boolean isTraceConversionOn()
          Indicates if character set conversion tracing is enabled.
static boolean isTraceDatastreamOn()
          Indicates if data stream tracing is enabled.
static boolean isTraceDiagnosticOn()
          Indicates if diagnostic tracing is enabled.
static boolean isTraceErrorOn()
          Indicates if error tracing is enabled.
static boolean isTraceInformationOn()
          Indicates if information tracing is enabled.
static boolean isTraceJDBCOn()
          Indicates if JDBC tracing is enabled.
static boolean isTraceOn()
          Indicates if overall tracing is enabled.
static boolean isTraceOn(int category)
          Indicates if tracing is enabled for the specified category.
static boolean isTracePCMLOn()
          Indicates if PCML tracing is enabled.
static boolean isTraceProxyOn()
          Indicates if proxy tracing is enabled.
static boolean isTraceThreadOn()
          Indicates if thread tracing is enabled.
static boolean isTraceWarningOn()
          Indicates if warning tracing is enabled.
static void log(int category, String message)
          Logs a message in the specified category.
static void log(int category, String message, boolean value)
          Logs a message and a boolean value in the specified category.
static void log(int category, String message, byte[] data)
          Logs a message and byte data in the specified category.
static void log(int category, String message, byte[] data, int offset, int length)
          Logs a message and byte data in the specified category.
static void log(int category, String message, int value)
          Logs a message and an integer value in the specified category.
static void log(int category, String message, Throwable e)
          Logs a message in the specified category.
static void log(int category, Throwable e)
          Logs a message in the specified category.
static void log(Object component, int category, String message)
          Logs a message for the specified component for the specified category.
static void log(Object component, int category, String message, boolean value)
          Logs a message and a boolean value in the specified category for the specified component.
static void log(Object component, int category, String message, byte[] data)
          Logs a message and byte data in the specified category for the specified component.
static void log(Object component, int category, String message, byte[] data, int offset, int length)
          Logs a message and byte data in the specified category for the specified component.
static void log(Object component, int category, String message, int value)
          Logs a message and an integer value in the specified category for the specified component.
static void log(Object component, int category, String message, Throwable e)
          Logs a message in the specified category for the specified component.
static void log(Object component, int category, Throwable e)
          Logs a message in the specified category for the specified component.
static void setFileName(Object component, String fileName)
          Sets the trace file name for the specified component.
static void setFileName(String fileName)
          Sets the trace file name.
static void setPrintWriter(Object component, PrintWriter obj)
          Sets the PrintWriter object for the specified component.
static void setPrintWriter(PrintWriter obj)
          Sets the PrintWriter object.
static void setTraceAllOn(boolean traceAll)
          Sets tracing for all categories on or off.
static void setTraceConversionOn(boolean traceConversion)
          Sets character set conversion tracing on or off.
static void setTraceDatastreamOn(boolean traceDatastream)
          Sets data stream tracing on or off.
static void setTraceDiagnosticOn(boolean traceDiagnostic)
          Sets diagnostic tracing on or off.
static void setTraceErrorOn(boolean traceError)
          Sets error tracing on or off.
static void setTraceInformationOn(boolean traceInformation)
          Sets information tracing on or off.
static void setTraceJDBCOn(boolean traceJDBC)
          Sets JDBC tracing on or off.
static void setTraceOn(boolean traceOn)
          Sets tracing on or off.
static void setTracePCMLOn(boolean tracePCML)
          Sets PCML tracing on or off.
static void setTraceProxyOn(boolean traceProxy)
          Sets proxy stream tracing on or off.
static void setTraceThreadOn(boolean traceThread)
          Sets thread tracing on or off.
static void setTraceWarningOn(boolean traceWarning)
          Sets warning tracing on or off.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DATASTREAM

public static final int DATASTREAM
'Data stream' trace category. This category is used by Toolbox classes to log data flow between the local host and the remote system. It is not intended for use by application classes.

See Also:
Constant Field Values

DIAGNOSTIC

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

See Also:
Constant Field Values

ERROR

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

See Also:
Constant Field Values

INFORMATION

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

See Also:
Constant Field Values

WARNING

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

See Also:
Constant Field Values

CONVERSION

public static final int CONVERSION
'Character set conversion' trace category. This category is used by Toolbox classes to log conversions between Unicode and native code pages. It is not intended for use by application classes.

See Also:
Constant Field Values

PROXY

public static final int PROXY
'Proxy' trace category. This category is used by Toolbox classes to log data flow between the client and the proxy server. It is not intended for use by application classes.

See Also:
Constant Field Values

PCML

public static final int PCML
'PCML' trace category. This category is used to determine how PCML interprets the data that is sent to and from the system.

See Also:
Constant Field Values

JDBC

public static final int JDBC
'JDBC' trace category. This category is used by the Toolbox JDBC driver to determine whether or not JDBC data should be included in the standard Toolbox trace. This setting is independent of what is set using the DriverManager class.

See Also:
Constant Field Values

LOGGER_NAME

public static final String LOGGER_NAME
Name of the instance of java.util.logging.Logger that the Toolbox uses. If no Logger by this name exists in the JVM, then traditional Toolbox tracing is done. To activate a Toolbox logger, the application can simply call Logger.getLogger(Trace.LOGGER_NAME).
Note: This constant resolves to the value com.ibm.as400.access.

See Also:
Constant Field Values
Method Detail

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.

getFileName

public static String getFileName(Object component)
Returns the trace file name for the specified component. Null is returned if no file name has been set for the component.

Returns:
The file name for the specified component. Null is returned if no file name has been set for the component.

getPrintWriter

public static PrintWriter getPrintWriter()
Returns the PrintWriter object.

Returns:
The PrintWriter object for the trace data output.

getPrintWriter

public static PrintWriter getPrintWriter(Object component)
Returns the print writer object for the specified component. Null is returned if no writer or file name has been set. If a file name for a component is set, that component automatically gets a print writer.

Returns:
The print writer object for the specified component. If no writer or file name has been set, null is returned.

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.

isTraceJDBCOn

public static final boolean isTraceJDBCOn()
Indicates if JDBC tracing is enabled.

Returns:
true if JDBC 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.

isTraceOn

public static final boolean isTraceOn(int category)
Indicates if tracing is enabled for the specified category.

Parameters:
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
Returns:
true if tracing for the category is enabled; false otherwise.

isTracePCMLOn

public static final boolean isTracePCMLOn()
Indicates if PCML tracing is enabled.

Returns:
true if PCML messages are traced; 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, JDBC].
message - The message to log.

log

public static final void log(Object component,
                             int category,
                             String message)
Logs a message for the specified component for the specified category. If the category is disabled, nothing is logged. If no print writer or file name has been set for the component, nothing is logged.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
message - The message to log.
e - The Throwable object that contains the stack trace to log.

log

public static final void log(Object component,
                             int category,
                             String message,
                             Throwable e)
Logs a message in the specified category for the specified component. If the category is disabled, nothing is logged.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
e - The Throwable object that contains the stack trace to log.

log

public static final void log(Object component,
                             int category,
                             Throwable e)
Logs a message in the specified category for the specified component. If the category is disabled, nothing is logged.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
message - The message to log.
value - The integer value to log.

log

public static final void log(Object component,
                             int category,
                             String message,
                             int value)
Logs a message and an integer value in the specified category for the specified component. If the category is disabled, nothing is logged. The integer value is appended to the end of the message, preceded by two blanks.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
message - The message to log.
value - The boolean data to log.

log

public static final void log(Object component,
                             int category,
                             String message,
                             boolean value)
Logs a message and a boolean value in the specified category for the specified component. 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:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
message - The message to log.
data - The bytes to log.

log

public static final void log(Object component,
                             int category,
                             String message,
                             byte[] data)
Logs a message and byte data in the specified category for the specified component. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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, JDBC].
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.

log

public static final void log(Object component,
                             int category,
                             String message,
                             byte[] data,
                             int offset,
                             int length)
Logs a message and byte data in the specified category for the specified component. If the category is disabled, nothing is logged. The byte data is appended to the end of the message, sixteen bytes per line.

Parameters:
component - The component to trace.
category - The message category [DATASTREAM, DIAGNOSTIC, ERROR, INFORMATION, WARNING, CONVERSION, PROXY, JDBC].
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(boolean)

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(boolean)

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(boolean)

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(boolean)

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(boolean)

setFileName

public static 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.

setFileName

public static void setFileName(Object component,
                               String fileName)
                        throws IOException
Sets the trace file name for the specified component. 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.
component - Trace data for this component goes to file fileName.
Throws:
IOException - If an error occurs while accessing the file.

setPrintWriter

public static 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.

setPrintWriter

public static void setPrintWriter(Object component,
                                  PrintWriter obj)
                           throws IOException
Sets the PrintWriter object for the specified component. All further trace output for this component is sent to the writer.

Parameters:
component - Trace data for this component goes to writer obj.
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(boolean)

setTraceJDBCOn

public static void setTraceJDBCOn(boolean traceJDBC)
Sets JDBC tracing on or off. The actual tracing does not happen unless tracing is on. If there is already a log writer or log stream registered with the DriverManager, then that one is used independent of the stream being used by this Toolbox Trace class. Replacing the log writer or log stream in use by the DriverManager after calling this method does not turn off this driver's JDBC tracing; it merely changes the destination of the output. In this way, it is possible to have JDBC trace data directed to 3 separate logging facilities: The stream used by this Trace class, the stream used by DriverManager.setLogStream(), and the writer used by DriverManager.setLogWriter().

Parameters:
traceJDBC - true to turn on JDBC tracing; false to turn it off.
See Also:
DriverManager

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.

setTracePCMLOn

public static void setTracePCMLOn(boolean tracePCML)
Sets PCML tracing on or off. The actual tracing does not happend unless tracing is on.

Parameters:
tracePCML - If true, PCML tracing is on; otherwise, PCML tracing is off.

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(boolean)

setTraceThreadOn

public static void setTraceThreadOn(boolean traceThread)
Sets thread tracing on or off. The actual tracing does not happen unless tracing is on.
Note: "thread" is not a separate trace category. That is, simply calling setTraceThreadOn(true) by itself will not cause any trace messages to be generated. Rather, it will cause additional thread-related information to be included in trace messages generated for other trace categories, such as "diagnostic" and "information".

Parameters:
traceThread - If true, thread tracing is on; otherwise, thread tracing is off.
See Also:
setTraceOn(boolean)

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(boolean)