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

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.
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.

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 -

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