1. Overview

The purpose of the JavaTrace library is to allow developers to inject debug or code flow trace statements in their code while developing programs without the risk of leaving those behind once the software is delivered to the client or customer. The most common method of injecting debug statements in Java programs is to use the System.out.println() method in its various forms. The disadvantage with this is that before the software is delivered these statements would have to removed from the code. Sometimes much effort can be spent behind this exercise. On the other hand, leaving these statements in the code provides valuable information while troubleshooting issues.

JavaTrace provides the best of both worlds - the ease of use of System.out.println() without the effort involved in removing these statements on delivery. The trace statements can be retained in the code and these can be turned on or off using a properties file.

Salient features of JavaTrace are:

• Enable/disable trace statements at the package or class levels
• Log trace statements to the console or to a user specified file
• Log trace statements using user specified logging class
• Works in standalone and web applications

JavaTrace is very simple to use and provides convenient methods to add trace statements in programs.

Back to menu

2. Installation

JavaTrace has been developed and tested on JDK 1.5.0. It can be used in standalone Java applications or Java Enterprise/Web Applications. For installation instructions click here.

Back to menu

3. Using JavaTrace

The behavior of JavaTrace can be controlled using a properties file called javatrace.properties. For more details on the various settings in the properties file see Section 5.

Using JavaTrace involves the following steps:

1. Set the correct properties in the javatrace.properties file (this file must be available in the CLASSPATH; see installation instructions)
2. Import org.jtrc.trace.JavaTrace into your code source files where you intend to inject trace messages
3. Use any of the following methods to add trace statements:
   • JavaTrace.addTraceHere()
   • JavaTrace.addTrace(String)
   • JavaTrace.addTrace(Object ...)

For more details on the methods please refer to the JavaTrace API Documentation.

Back to menu

4. JavaTrace Loggers

The trace statements added using JavaTrace are by default output to the application console. In order to persist these statements logging classes or loggers can be used. JavaTrace ships with the following loggers:

• org.jtrc.logger.JtrcConsoleLogger: This logger logs all trace messages to the default console of the application.
• org.jtrc.logger.JtrcFileLogger: This logger logs all trace messages to a user specified file.

The use of the above mentioned loggers is totally transparent to the developer.

In order to use the file logger set the following properties in the javatrace.properties file:

• jtrc.trace.log.file=<path to the trace file; all trace messages would be written to this>
• jtrc.log.mode=[append|overwrite]<The mode in which the trace file will be opened. The default option is overwrite.>

If none of the above are set, or in case of any error during initialization of the file logger, JavaTrace defaults to the console logger.

Apart from the above mentioned loggers, JavaTrace also allows developers to specify custom logging classes. Custom logging classes can be used to store trace messages to a database table or to a JMS queue. If a custom logging class is specified, it would be used regardless of whether the JavaTrace file logger properties are set in the javatrace.properties file or not.

To use custom loggers:

• Implement the org.jtrc.logger.JtrcLogger interface in your custom logging class. This class should have a default or zero parameter constructor. See the API Documentation for more details on this interface.
• Specify the customer logger class in the javatrace.properties as follows:
  • jtrc.logger.class=<fully qualified class name>

The custom class should be available in the CLASSPATH. In case of any error being raised while instantiating the custom logger, JavaTrace defaults to the console logger.

Back to menu

5. javatrace.properties File

Behavior of JavaTrace is controlled through a properties file named javatrace.properties. This properties file contains all the properties required for the functioning of JavaTrace.

Detailed description of each of these properties follows.

jtrc.trace.enabled

This property determines whether tracing will be enabled for the whole application or not. Allowed values are:

• true
• false

Setting this to true enables application wide tracing for the declared elements. A value of false disables tracing. The default value is false.

jtrc.trace.log.file

This property is used to specify a log file location where all the trace messages will be persisted. Specifying this property causes JavaTrace to use the default file logger.

jtrc.log.mode

This property determines how the log file will be opened to persist trace messages. This property is used only if the JavaTrace file logger is activated using the jtrc.trace.log.file property. Possible values are:

• append : Appends trace messages to the already existing messages in the file
• overwrite : Overwrites all existing messages

The default value is overwrite.

jtrc.logger.class

JavaTrace messages can also be persisted to a database or to a JMS queue. In order to do so, custom loggers need to be provided to JavaTrace. For more details on custom loggers see Section 4. The fully qualified class name(<package name>.<class name>) should be specified as the value for this property. If a custom logger is specified the settings of the jtrc.trace.log.file and jtrc.log.mode are ignored.

Enabling tracing for elements

JavaTrace allows a developer to enable trace messages at a class level or package level. The following values are allowed to enable or disable tracing:

• true: Enables tracing for the element
• false: Disables tracing for the element

To enable tracing at the class level specify the fully qualified class names as follows:

To enable tracing at the package level, specify the package names as follows:

Enabling tacing for a package enables tracing on all the classes and sub-packages of that package.

The order of declaration is important. Consider the following declarations:

This will still enable tracing for ClassA as it was declared ahead of org.foo.

Back to menu

6. Limitations

JavaTrace makes use of some predefined strings as keys in the javatrace.properties file. It is assumed that the developer application will not have the following package names:

• jtrc.trace.enabled
• jtrc.trace.log.file
• jtrc.log.mode
• jtrc.logger.class

Back to menu

7. Example

The following is an example of how to use JavaTrace during development:

The first source file:

// Source file 1

package com.jtsimtest.pkg1;

// Import the class
import org.jtrc.trace.JavaTrace;

import com.jtsimtest.pkg2.Pkg2Class;

/**
 * This class demonstrates the use of 
 * the JavaTrace methods. 
 */
public class SimpleJavaTraceTest
{
  private static void doNothingReally()
  {
    String aString = "This is a string";
    String hello = " hello world";
		

    // Here's a trace call
    JavaTrace.addTrace(aString, hello);

    
    Pkg2Class obj2 = new Pkg2Class();
    int i = 3 + obj2.getTheValue();


    // Here's another trace call
    JavaTrace.addTrace("This is where we are and the value of i = " + i);

  }

  /**
   * The main method.
   * @param ar The passed arguments
   */
  public static void main(String ar[])
  {

    // A default trace statement
    JavaTrace.addTraceHere();

    doNothingReally();
  }
}
				

The second source file:

// Source file 2

package com.jtsimtest.pkg2;

// Import the class
import org.jtrc.trace.JavaTrace;

/**
 * Another class with trace
 * statements
 */
public class Pkg2Class
{
  /**
   * This method returns a fixed value 
   * of 125.
   * @return The fixed value
   */
  public int getTheValue()
  {
    // Add a trace statement
    JavaTrace.addTrace("In the getTheValue() method of Pkg2Class");
      
    return 125;
  }
}

				

These source files were then compiled using the Java compiler with the JavaTrace library in the CLASSPATH. See installation instructions for more details.

Following is the contents of the javatrace.properties file:

# The settings
jtrc.trace.enabled=true
jtrc.trace.log.file=
jtrc.log.mode=append
jtrc.logger.class=

# Enabling tracing for all classes
com=true				
				

The contents of the directory now are:

$CONTENT_ROOT/javatrace.jar
$CONTENT_ROOT/javatrace.properties
$CONTENT_ROOT/com/jtsimtest/pkg1/SimpleJavaTraceTest.class
$CONTENT_ROOT/com/jtsimtest/pkg2/Pkg2Class.class

Command used to run the example program from the console:

java -cp "./javatrace.jar;./" com.jtsimtest.pkg1.SimpleJavaTraceTest

The output in the console:

Back to menu