Trace class

Trace class

The Trace class logs the following categories of information:

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

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");