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 this 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). Other methods of this class are mostly to be used while debugging and do not use keys for filtering.

Author:

bamade

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.

Constructor Summary

Constructors

Constructor and Description
Tracer()

Method Summary

Methods

Modifier and Type	Method and Description
static String[]	getKeys()
static Tracer.Strategy	getReporter()
static boolean	injectSideEffect(String enablingSystemProperty, Runnable sideEffectCode) normally assertion should not have side-effects.
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.
static boolean	traceInfos(Object obj) traces the package infos of a Class (including version).
static boolean	traceOurMavenProperties(String projectName) traces non-standard $Project.maven.properties.
static boolean	tracePomProperties(String orgName, String projectName) traces standard pom properties as deployed by maven.
static boolean	traceProperties(Object obj, String propFile) Trace properties linked to an object.
static boolean	traceWhere(Object obj) traces where a class comes from.
static boolean	version(String vcsString, Class clazz, String projectName)
static boolean	version(String vcsString, Class clazz, String orgName, String projectName)

Methods inherited from class java.lang.Object

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

Constructor Detail

Tracer

public Tracer()

Method Detail

setReporter

public static void setReporter(Tracer.Strategy reporter)

getReporter

public static Tracer.Strategy getReporter()

getKeys

public static String[] getKeys()

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 -

traceProperties

public static boolean traceProperties(Object obj,
                      String propFile)

Trace properties linked to an object. This method always traces and does not use filtering "keys".

Parameters:

obj -

propFile - name of the property file (without leading slash

Returns:

always true (for use in assertions)

traceInfos

public static boolean traceInfos(Object obj)

traces the package infos of a Class (including version). This method always traces and does not use filtering "keys".

Parameters:

obj - can be an Object or a Class

Returns:

always true

traceWhere

public static boolean traceWhere(Object obj)

traces where a class comes from. This method always traces and does not use filtering "keys".

Parameters:

obj - can be an Object or a Class

Returns:

always true

tracePomProperties

public static boolean tracePomProperties(String orgName,
                         String projectName)

traces standard pom properties as deployed by maven. This method always traces and does not use filtering "keys".

Parameters:

orgName - name of organisation ("org.lsst")

projectName - name of project ("org-lsst-ccs-core")

Returns:

traceOurMavenProperties

public static boolean traceOurMavenProperties(String projectName)

traces non-standard $Project.maven.properties. This method always traces and does not use filtering "keys".

Parameters:

projectName - name of project ("org-lsst-ccs-core")

Returns:

always true

version

public static boolean version(String vcsString,
              Class clazz,
              String orgName,
              String projectName)

Parameters:

vcsString - the caller should have put the result of a subversion evaluation (variables Rev, Author between '$' chars)

clazz -

orgName - such as org.lsst

projectName -

Returns:

version

public static boolean version(String vcsString,
              Class clazz,
              String projectName)

injectSideEffect

public static boolean injectSideEffect(String enablingSystemProperty,
                       Runnable sideEffectCode)

normally assertion should not have side-effects. This method circumvents this rule: if a system property is set the Runnable will be executed and might have side-effects. This can be used to "inject" specific testing behaviours in a class.

Parameters:

enablingSystemProperty - the name of a boolean system property that allows this code to be run

sideEffectCode - the code that will be executed in the current Thread (beware: exceptions not caught!)

Returns:

always true