de.christofreichardt.diagnosis

Class AbstractTracer

java.lang.Object

de.christofreichardt.diagnosis.AbstractTracer

Direct Known Subclasses:

DebugLogTee, FileTracer, NetTracer, NullTracer, QueueTracer

public abstract class AbstractTracer
extends Object

Defines the basic behaviour of tracers. A tracer comes with a map which maps threads on so called TracingContexts. Each of these TracingContexts manage a stack of TraceMethods. To be observed methods can be pushed on the method stack assigned to the current thread. When a method is pushed on the stack a notification will be written to an output stream. When the method is popped from the stack again a notification will be written together with the elapsed time too.

A TracePrintStream can be used to print additional output. Dependent on the size of the stack the output can be intended thus providing a clearly arranged format. If the size of the stack exceeds a configured limit the tracing output will be discarded. If the stack size decreases below this limit the output will be printed again.

It's possible for a tracer to manage a stack for more than one thread. Then it's the responsibility of the client to synchronize access to the output stream with getSyncObject(). However it is recommended to use another tracer for each thread.

A distinction is made between tracing and logging. Log messages can be redirected to conventional logging systems such as the logging system of the Java platform or log4j, see for an example JDKLoggingRouter and FileTracerLog4jTee.

Before a tracer generates output it must be opened and the tracing context of the current thread must be initialised, e.g.:

 final AbstractTracer tracer = new FileTracer("Example");
 tracer.open();
 try {
   class Foo {
     void bar() {
       tracer.entry("void", this, "bar()");
       try {
         tracer.out().printfIndentln("This is an example.");
       }
       finally {
         tracer.wayout();
       }
     }
   }
   Foo foo = new Foo();
   foo.bar(); // nothing will be printed because no tracing context has been provided
   tracer.initCurrentTracingContext(2, true);
   foo.bar(); // this will generate output
 }
 finally {
   tracer.close();
 }

The generated output can be found at ./log/Example.log - whereas the directory ./log must exist - and looks like:

 --> TraceLog opened!
     Time     : Mi Apr 02 23:14:41 MESZ 2014
     Bufsize  : 512
     Autoflush: true
 
 ENTRY--void Foo[12275192].bar()--main[1]
   This is an example.
 RETURN-void Foo[12275192].bar()--(+0ms)--(+0ms)--main[1]
 
 --> TraceLog closing!
     Time     : Mi Apr 02 23:14:41 MESZ 2014
 

Author:

Christof Reichardt

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AbstractTracer.Exception Indicates exceptional states within the AbstractTracer context.

Field Summary

Fields

Modifier and Type	Field and Description
static String	VERSION

Constructor Summary

Constructors

Constructor and Description
AbstractTracer(String name) Constructor expects a name for the tracer, preferably unique.

Method Summary

Modifier and Type	Method and Description
void	clearCurrentTracingContext() Removes the current tracing context, that is - for example - subsequent calls to out() from the current thread will return the NullPrintStream.
abstract void	close() Derived classes should provide code that closes the output streams.
TraceMethod	entry(String methodSignature) Deprecated. use entry(String returnType, Class clazz, String methodSignature) or entry(String returnType, Object object, String methodSignature)
TraceMethod	entry(String returnType, Class clazz, String methodSignature) Indicates an entering of a method which belongs to a class.
TraceMethod	entry(String returnType, Object object, String methodSignature) Indicates an entering of a method which belongs to an object.
protected String	formatStreamErrorState() Gives a string representation about the error state of the IndentablePrintStream of this Tracer instance.
protected String	formatVersionInfo() Gives a string representation about the version of this library.
protected BufferedOutputStream	getBufferedOutputStream() Derived classes may use this getter to retrieve the buffer of the actual TracePrintStream.
int	getBufferSize() Gives the buffer size of the actual TracePrintStream.
String	getName() The name of the tracer.
protected NullPrintStream	getNullPrintStream() A replacement for /dev/null.
Object	getSyncObject() Synchronizes access to the TracePrintStream.
protected AbstractThreadMap	getThreadMap() Provides access to the tracing contexts indexed by Threads.
protected TracePrintStream	getTracePrintStream() Derived classes may use this getter to retrieve the actual TracePrintStream.
void	initCurrentTracingContext() Initialises the current tracing context by taking the values for debugLevel and online from the configured debug map.
void	initCurrentTracingContext(int debugLevel, boolean online) Initialises the current tracing context with the given debugLevel and online state.
boolean	isAutoflush() Indicates whether the output stream will be flushed when leaving a method by wayout().
boolean	isOpened() Indicates whether the actual TracePrintStream is opened.
void	logException(LogLevel logLevel, Throwable throwable, Class clazz, String methodName) Logs an exception with the given logLevel and the originating class.
void	logMessage(LogLevel logLevel, String message, Class clazz, String methodName) Logs a message with the given logLevel and the originating class.
abstract void	open() Derived classes should provide code that opens the respective output streams.
IndentablePrintStream	out() Returns some kind of an IndentablePrintStream based upon the the current managed stack size, the configured debug level and the online state of the current tracing context.
protected IndentablePrintStream	out(int level) Returns some kind of an IndentablePrintStream based upon the given level, the configured debug level and the online state of the current tracing context.
protected void	readConfiguration(XPath xpath, Node node) Reads the configuration for this particular tracer instance by evaluating the given node with the given xpath engine.
protected void	setAutoflush(boolean autoflush) Used during the configuration.
protected void	setBufferedOutputStream(BufferedOutputStream bufferedOutputStream) Derived classes may use this setter to inform the base class about the buffer of the actual TracePrintStream.
void	setBufferSize(int bufferSize) Configures the buffer size of the actual TracePrintStream.
protected void	setOpened(boolean opened) Derived classes may use this method to inform the base class that the actual TracePrintStream is opened.
protected void	setTracePrintStream(TracePrintStream tracePrintStream) Derived classes may use this setter to inform the base class about the actual TracePrintStream.
protected String	substitute(String expression) Replaces the given argument by repeatedly substituting all expressions of the form ${property-key} with the corresponding property value.
TraceMethod	wayout() Indicates the exiting of a method.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final String VERSION

See Also:

Constant Field Values

Constructor Detail

AbstractTracer

public AbstractTracer(String name)

Constructor expects a name for the tracer, preferably unique.

Parameters:

name - the name of the tracer.

Method Detail

getName

public String getName()

The name of the tracer.

Returns:

the name

isOpened

public boolean isOpened()

Indicates whether the actual TracePrintStream is opened.

Returns:

the opened

setOpened

protected void setOpened(boolean opened)

Derived classes may use this method to inform the base class that the actual TracePrintStream is opened.

Parameters:

opened - the opened to set

isAutoflush

public boolean isAutoflush()

Indicates whether the output stream will be flushed when leaving a method by wayout().

Returns:

the autoflush

setAutoflush

protected void setAutoflush(boolean autoflush)

Used during the configuration. Indicates whether the output stream will be flushed when leaving a method by wayout().

Parameters:

autoflush - the autoflush to set

getBufferSize

public int getBufferSize()

Gives the buffer size of the actual TracePrintStream.

Returns:

the bufferSize

setBufferSize

public void setBufferSize(int bufferSize)

Configures the buffer size of the actual TracePrintStream.

Parameters:

bufferSize - the bufferSize to set

getSyncObject

public Object getSyncObject()

Synchronizes access to the TracePrintStream. Clients with multiple TracingContexts should use it to synchronize their access to out().

Returns:

the syncObject

getNullPrintStream

protected NullPrintStream getNullPrintStream()

A replacement for /dev/null.

Returns:

the nullPrintStream

getBufferedOutputStream

protected BufferedOutputStream getBufferedOutputStream()

Derived classes may use this getter to retrieve the buffer of the actual TracePrintStream.

Returns:

the bufferedOutputStream

See Also:

open(), close()

setBufferedOutputStream

protected void setBufferedOutputStream(BufferedOutputStream bufferedOutputStream)

Derived classes may use this setter to inform the base class about the buffer of the actual TracePrintStream.

Parameters:

bufferedOutputStream - the bufferedOutputStream to set

See Also:

open(), close()

getTracePrintStream

protected TracePrintStream getTracePrintStream()

Derived classes may use this getter to retrieve the actual TracePrintStream.

Returns:

the tracePrintStream

See Also:

open(), close()

setTracePrintStream

protected void setTracePrintStream(TracePrintStream tracePrintStream)

Derived classes may use this setter to inform the base class about the actual TracePrintStream.

Parameters:

tracePrintStream - the tracePrintStream to set

See Also:

open(), close()

getThreadMap

protected AbstractThreadMap getThreadMap()

Provides access to the tracing contexts indexed by Threads.

Returns:

the threadMap

readConfiguration

protected void readConfiguration(XPath xpath,
                                 Node node)
                          throws XPathExpressionException,
                                 AbstractTracer.Exception

Reads the configuration for this particular tracer instance by evaluating the given node with the given xpath engine.

Parameters:

xpath - the xpath engine

node - the config node

Throws:

XPathExpressionException - indicates xpath problems

AbstractTracer.Exception - indicates problems when configuring certain tracer instances

open

public abstract void open()

Derived classes should provide code that opens the respective output streams.

close

public abstract void close()

Derived classes should provide code that closes the output streams.

out

public IndentablePrintStream out()

Returns some kind of an IndentablePrintStream based upon the the current managed stack size, the configured debug level and the online state of the current tracing context. This is the NullPrintStream if the stack size is greater than the debug level or if the thread is offline. Otherwise it's the TracePrintStream.

Returns:

an IndentablePrintStream

out

protected IndentablePrintStream out(int level)

Returns some kind of an IndentablePrintStream based upon the given level, the configured debug level and the online state of the current tracing context. It will be the NullPrintStream if the given level is greater than the debug level or if the thread is offline. Otherwise it's the TracePrintStream.

Parameters:

level - the level of the to be printed data

Returns:

an IndentablePrintStream

entry

@Deprecated
public TraceMethod entry(String methodSignature)

Deprecated. use entry(String returnType, Class clazz, String methodSignature) or entry(String returnType, Object object, String methodSignature)

Indicates an entering of a method.

Parameters:

methodSignature - the signature of the method as string representation

Returns:

the TraceMethod which has been put onto the stack - a mere data object for internal use primarily. May be null.

entry

public TraceMethod entry(String returnType,
                         Object object,
                         String methodSignature)

Indicates an entering of a method which belongs to an object. If a TracingContext exists for the current thread a TraceMethod object will be created and thereupon pushed onto the stack of a ThreadMap.

Parameters:

returnType - the return type of the method as string representation

object - the object that owns the method

methodSignature - the remaining method signature (without return type) inclusive parameter as string representation

Returns:

the TraceMethod which has been put onto the stack - a mere data object for internal use primarily. May be null.

entry

public TraceMethod entry(String returnType,
                         Class clazz,
                         String methodSignature)

Indicates an entering of a method which belongs to a class. If a TracingContext exists for the current thread a TraceMethod object will be created and thereupon pushed onto the stack of a ThreadMap.

Parameters:

returnType - the return type of the method as string representation

clazz - the class to which that method belong

methodSignature - the remaining method signature (without return type) inclusive parameter as string representation

Returns:

the TraceMethod which has been put onto the stack - a mere data object for internal use primarily. May be null.

wayout

public TraceMethod wayout()

Indicates the exiting of a method.

Returns:

the TraceMethod which has been popped from the stack - a mere data object for internal use primarily. May be null.

logMessage

public void logMessage(LogLevel logLevel,
                       String message,
                       Class clazz,
                       String methodName)

Logs a message with the given logLevel and the originating class.

Parameters:

logLevel - one of the predefined levels INFO, WARNING, ERROR, FATAL and SEVERE

message - the to be logged message

clazz - the originating class

methodName - the originating method

logException

public void logException(LogLevel logLevel,
                         Throwable throwable,
                         Class clazz,
                         String methodName)

Logs an exception with the given logLevel and the originating class.

Parameters:

logLevel - one of the predefined levels INFO, WARNING, ERROR, FATAL and SEVERE

throwable - the to be logged throwable

clazz - the originating class

methodName - the name of the relevant method

initCurrentTracingContext

public void initCurrentTracingContext(int debugLevel,
                                      boolean online)

Initialises the current tracing context with the given debugLevel and online state.

Parameters:

debugLevel - controls the extent of the output

online - a value of false delivers no output of the current thread at all whereas a value of true delivers output controlled by debugLevel

initCurrentTracingContext

public void initCurrentTracingContext()

Initialises the current tracing context by taking the values for debugLevel and online from the configured debug map.

clearCurrentTracingContext

public void clearCurrentTracingContext()

Removes the current tracing context, that is - for example - subsequent calls to out() from the current thread will return the NullPrintStream.

substitute

protected String substitute(String expression)
                     throws AbstractTracer.Exception

Replaces the given argument by repeatedly substituting all expressions of the form ${property-key} with the corresponding property value.

Parameters:

expression - the to be replaced expression

Returns:

the replaced expression

Throws:

AbstractTracer.Exception - indicates problems during the replacement

formatStreamErrorState

protected String formatStreamErrorState()

Gives a string representation about the error state of the IndentablePrintStream of this Tracer instance.

Returns:

a formatted status line

formatVersionInfo

protected String formatVersionInfo()

Gives a string representation about the version of this library.

Returns:

a formatted status line