Trace class

The Trace class allows the Java™ program to log trace points and diagnostic messages. This information helps reproduce and diagnose problems.

Note: You can also set tracing by using the trace system properties.

The Trace class logs the following categories of information:

Information category	Description
Conversion	Logs character set conversions between Unicode and code pages. This category is used only by the IBM® Toolbox for Java classes.
Datastream	Logs the data that flows between the system and the Java program. This category is used only by the IBM Toolbox for Java classes.
Diagnostic	Logs state information.
Error	Logs additional errors that cause an exception.
Information	Traces the flow through a program.
PCML	This category is used to determine how PCML interprets the data that is sent to and from the server.
Proxy	This category is used by IBM Toolbox for Java classes to log data flow between the client and the proxy server.
Warning	Logs information about errors the program was able to recover from.
All	This category is used to enable or disable tracing for all of the above categories at once. Trace information cannot be directly logged to this category.

The IBM Toolbox for Java classes also use the trace categories. When a Java program enables logging, IBM Toolbox for Java information is included with the information that is recorded by the application.

You can enable the trace for a single category or a set of categories. Once the categories are selected, use the setTraceOn method to turn tracing on and off. Data is written to the log using the log method.

You can send trace data for different components to separate logs. Trace data, by default, is written to the default log. Use component tracing to write application-specific trace data to a separate log or standard output. By using component tracing, you can easily separate trace data for a specific application from other data.

Excessive logging can impact performance. Use the isTraceOn method to query the current state of the trace. Your Java program can use this method to determine whether it builds the trace record before it calls the log method. Calling the log method when logging is off is not an error, but it takes more time.

The default is to write log information to standard out. To redirect the log to a file, call the setFileName() method from your Java application. In general, this works only for Java applications because most browsers do not give applets access to write to the local file system.

Logging is off by default. Java programs provide a way for the user to turn on logging so that it is easy to enable logging. For example, the application can parse for a command line parameter that indicates which category of data is logged. The user can set this parameter when log information is needed.

Examples

Note: Read the Code example disclaimer for important legal information.

The following examples show how to use the Trace class.

Example Using setTraceOn() and writing data to a log by using the log method

     // Enable diagnostic, information, and warning logging.
     Trace.setTraceDiagnosticOn(true);
     Trace.setTraceInformationOn(true);
     Trace.setTraceWarningOn(true);
 
     // Turn tracing on.
     Trace.setTraceOn(true);
 
     // ... At this point in the Java program, write to the log.
     Trace.log(Trace.INFORMATION, "Just entered class xxx, method xxx");

     // Turning tracing off.
     Trace.setTraceOn(false);

Example: Using Trace

In the following code, Method 2 is the preferable way to use Trace.

     // Method 1 - build a trace record
     // then call the log method and let the trace class determine if the
     // data should be logged. This will work but will be slower than the
     // following code.
     String traceData = new String("Just entered class xxx, data = ");
     traceData = traceData + data + "state = " + state;
     Trace.log(Trace.INFORMATION, traceData);
 
     // Method 2 - check the log status before building the information to
     // log. This is faster when tracing is not active.
     if (Trace.isTraceOn() && Trace.isTraceInformationOn())
     {
        String traceData = new String("just entered class xxx, data = ");
        traceData = traceData + data + "state = " + state;
        Trace.log(Trace.INFORMATION, traceData);
     }

Example: Using component tracing

     // Create a component string. It is more efficient to create an
     // object than many String literals.
     String myComponent1 = "com.myCompany.xyzComponent";
     String myComponent2 = "com.myCompany.abcComponent";
         
     // Send IBM Toolbox for Java and the component trace data each to separate files.
     // The trace will contain all trace information, while each
     // component log file will only contain trace information specific to
     // that component.  If a Trace file is not specified, all trace data
     // will go to standard out with the component specified in front of
     // each trace message.

     // Trace.setFileName("c:\\bit.bucket");       
     // Trace.setFileName(myComponent1, "c:\\Component1.log");
     // Trace.setFileName(myComponent2, "c:\\Component2.log");

     Trace.setTraceOn(true);             // Turn trace on.
     Trace.setTraceInformationOn(true);  // Enable information messages. 
         
     // Log component specific trace data or general IBM Toolbox for Java
     // trace data.
    
     Trace.setFileName("c:\\bit.bucket");       
     Trace.setFileName(myComponent1, "c:\\Component1.log");