org.lsst.ccs.utilities.tracers
Class Tracer

java.lang.Object
  org.lsst.ccs.utilities.tracers.Tracer

public class Tracer
extends Object

Utility to add traces to a code.

Though it is a hack on assertions this can be used that way

 import static org.lsst.ccs.utilities.tracers.Tracer.* ;
 ....
 public void myMethod(int arg) {
      assert trace("myMethod called with" +arg) ;
 // code
 }
 

 public void anotherMethod(String arg) {
      assert stackTrace() ;
 }
 

A developper can also use home-grown filters

 import static org.lsst.ccs.utilities.tracers.Tracer.* ;
 import org.lsst.ccs.mypackage.MyEnum ;
 ....
 public void myMethod(int arg) {
     assert trace(MyEnum.DOING_THIS, "myMethod called with" +arg) ;
 // code
 }
 

 public void anotherMethod(String arg) {
    assert stackTrace(MyEnum.DOING_THAT) ;
 }
 

then if System property org.lsst.ccs.traces is set the traces can be produced or not. Example of option -Dorg.lsst.ccs.traces=DOING_THIS,DOING_THAT

By default the strings are printed to System.out but ths can be changed. If you want to delegate the reporting to another code (such as a Logger) write a code implementing Tracer.Strategy and deploy it using the ServiceLoader (or put the canonical className as value for property org.lsst.ccs.traceReporter).

Author:

bamade

Nested Class Summary

static class	Tracer.MultiReporter Convenience class to create a code that reports to many report "handlers".
static interface	Tracer.Strategy defines the behaviour of a tracer.

Field Summary

protected static String[]	keys
static Tracer.Strategy	reporter

Constructor Summary

Tracer()

Method Summary

static Tracer.Strategy	getReporter()
static void	setReporter(Tracer.Strategy reporter)
static boolean	stackTrace() reports a complete stack trace of the current code execution.
protected static void	stackTrace(int levelOut) reports part a stacktrace starting at index levelOut
static boolean	stackTrace(String filter) reports a complete stack trace of the current code execution only if the filter string is part of the org.lsst.ccs.traces property.
static <T extends Enum> boolean	stackTrace(T enumElement) reports a complete stack trace of the current code execution only if the filter enum constant is cited in the org.lsst.ccs.traces property.
static boolean	trace(String traceString) utility method to fire a trace.
static boolean	trace(String filter, String traceString) reports a trace only if the filter string is part of the org.lsst.ccs.traces property.
static <T extends Enum> boolean	trace(T enumElement, String traceString) uses an enum constant to filter the message passed to the tracer.

Methods inherited from class java.lang.Object

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

Field Detail

reporter

public static Tracer.Strategy reporter

keys

protected static String[] keys

Constructor Detail

Tracer

public Tracer()

Method Detail

setReporter

public static void setReporter(Tracer.Strategy reporter)

getReporter

public static Tracer.Strategy getReporter()

trace

public static boolean trace(String traceString)

utility method to fire a trace. Though it is not mandatory this method could be used as a side-effect of an assert (this is not a politically correct use of the assert feature).

Parameters:

traceString - will always be transmitted to code for reporting the trace

Returns:

trace

public static boolean trace(String filter,
                            String traceString)

reports a trace only if the filter string is part of the org.lsst.ccs.traces property. It is highly recommended to use enums instead of Strings to operate this filtering.

Parameters:

filter -

traceString -

Returns:

trace

public static <T extends Enum> boolean trace(T enumElement,
                                             String traceString)

uses an enum constant to filter the message passed to the tracer.

Type Parameters:

T -

Parameters:

enumElement -

traceString -

Returns:

stackTrace

public static boolean stackTrace()

reports a complete stack trace of the current code execution. It is highly recommended to use with an assert and preferably with a filter.

Returns:

stackTrace

public static boolean stackTrace(String filter)

reports a complete stack trace of the current code execution only if the filter string is part of the org.lsst.ccs.traces property.

Parameters:

filter -

Returns:

stackTrace

public static <T extends Enum> boolean stackTrace(T enumElement)

reports a complete stack trace of the current code execution only if the filter enum constant is cited in the org.lsst.ccs.traces property.

Type Parameters:

T -

Parameters:

enumElement -

Returns:

stackTrace

protected static void stackTrace(int levelOut)

reports part a stacktrace starting at index levelOut

Parameters:

levelOut -