com.townleyenterprises.trace
Class BasicTrace

java.lang.Object
  com.townleyenterprises.trace.TraceCore
      com.townleyenterprises.trace.MethodTrace
          com.townleyenterprises.trace.BasicTrace

public class BasicTrace

extends MethodTrace

This class implements a proposal by Phil Hourihane (one of my colleagues at Meridian) as a compromise to still have the tracing capabilites, but reduce the number of lines of code required to provide complete (or mostly complete) coverage of the exits from methods expected to throw exceptions. Personally, I still feel that this approach is no substitute for the fully instrumented version, but I can see why it might be desirable to implement.

This class should be used in the following manner to instrument a method:

 	...
 	private static BasicTrace _trace = new BasicTrace("MyClass", 0);
	...
 	
 	public int someMethod(String param1, int param2) throws Exception
 	{
 		final String[] pnames = new String[] { "param1", "param2" };
 		_trace.methodStart("someMethod", pnames,
 			new Object[] { param1, new Integer(param2) });

 		int rc = 0;
 		try
 		{
 			// code that could throw an exception
 			...
 			return _trace.methodReturn(rc);
 		}
 		finally
 		{
 			_trace.methodExit();
 		}
 	}
 

The idea here is that you still get the entry and exit in the normal case, but you don't have to attempt to check for all possible exceptions which could be thrown (and upset the method name stack of the MethodTrace class).

Version:

$Id: BasicTrace.java,v 1.1 2004/11/27 17:32:50 atownley Exp $

Author:

Phil Hourihane (API specification), Andrew S. Townley

Field Summary

static java.lang.String

TRACE_EXIT_FMT This method indicates a normal trace return

Fields inherited from class com.townleyenterprises.trace.MethodTrace

TRACE_ARG_GEN_FMT, TRACE_ARG_STR_FMT, TRACE_RETURN_FMT, TRACE_RETURN_GEN_FMT, TRACE_RETURN_STR_FMT, TRACE_START_FMT, TRACE_THROW_FMT

Constructor Summary

BasicTrace(java.lang.String name)
The constructor initializes the trace core instance.

BasicTrace(java.lang.String name, int maturity)
The constructor initializes the trace core instance.

BasicTrace(java.lang.String name, int maturity, int threshold)
This constructor also sets the threshold when the method information will be printed (overriding the default value of 1).

Method Summary

void	methodExit() This method should be called to indicate a normal exit from the method (either as a result of an exception, or from no exception being thrown.

Methods inherited from class com.townleyenterprises.trace.MethodTrace

methodArg, methodArg, methodArg, methodArg, methodArg, methodArg, methodArgs, methodReturn, methodReturn, methodReturn, methodReturn, methodReturn, methodReturn, methodReturn, methodReturn, methodReturn, methodStart, methodStart, methodStart, methodThrow, methodThrow, popCurrentMethod

Methods inherited from class com.townleyenterprises.trace.TraceCore

getInstanceTraceLevel, getShowThreadNameAlways, getShowTimestamp, getTimestampFormat, getTraceFile, getTraceLevel, getTraceLevel, getTraceStream, loadInstanceSettings, loadSettings, printStackTrace, setInstanceTraceLevel, setShowThreadNameAlways, setShowTimestamp, setTimestampFormat, setTraceFile, setTraceLevel, setTraceLevel, tprintln, tprintln, willTrace

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TRACE_EXIT_FMT

public static final java.lang.String TRACE_EXIT_FMT

This method indicates a normal trace return

See Also:

Constant Field Values

Constructor Detail

BasicTrace

public BasicTrace(java.lang.String name)

The constructor initializes the trace core instance.

BasicTrace

public BasicTrace(java.lang.String name,
                  int maturity)

The constructor initializes the trace core instance.

BasicTrace

public BasicTrace(java.lang.String name,
                  int maturity,
                  int threshold)

This constructor also sets the threshold when the method information will be printed (overriding the default value of 1).

Parameters:

name - the trace name

maturity - the maturity of the class

threshold - the default threshold

Method Detail

methodExit

public void methodExit()

This method should be called to indicate a normal exit from the method (either as a result of an exception, or from no exception being thrown.