public abstract class AbstractTracer extends Object
Defines the basic behaviour of tracers. A tracer comes with a map which maps threads on so called
TracingContext
s. Each of these TracingContext
s manage a stack of TraceMethod
s.
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
Modifier and Type | Class and Description |
---|---|
class |
AbstractTracer.Exception
Indicates exceptional states within the AbstractTracer context.
|
Constructor and Description |
---|
AbstractTracer(String name)
Constructor expects a name for the tracer, preferably unique.
|
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)
|
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.
|
public static final String VERSION
public AbstractTracer(String name)
name
- the name of the tracer.public String getName()
public boolean isOpened()
TracePrintStream
is opened.protected void setOpened(boolean opened)
TracePrintStream
is opened.opened
- the opened to setpublic boolean isAutoflush()
wayout()
.protected void setAutoflush(boolean autoflush)
wayout()
.autoflush
- the autoflush to setpublic int getBufferSize()
TracePrintStream
.public void setBufferSize(int bufferSize)
TracePrintStream
.bufferSize
- the bufferSize to setpublic Object getSyncObject()
TracePrintStream
. Clients with multiple TracingContext
s should use it to synchronize their access to
out()
.protected NullPrintStream getNullPrintStream()
protected BufferedOutputStream getBufferedOutputStream()
TracePrintStream
.protected void setBufferedOutputStream(BufferedOutputStream bufferedOutputStream)
TracePrintStream
.protected TracePrintStream getTracePrintStream()
TracePrintStream
.protected void setTracePrintStream(TracePrintStream tracePrintStream)
TracePrintStream
.protected AbstractThreadMap getThreadMap()
protected void readConfiguration(XPath xpath, Node node) throws XPathExpressionException, AbstractTracer.Exception
xpath
- the xpath enginenode
- the config nodeXPathExpressionException
- indicates xpath problemsAbstractTracer.Exception
- indicates problems when configuring certain tracer instancespublic abstract void open()
public abstract void close()
public IndentablePrintStream out()
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
.IndentablePrintStream
protected IndentablePrintStream out(int level)
NullPrintStream
if the given level is greater
than the debug level or if the thread is offline. Otherwise it's the TracePrintStream
.level
- the level of the to be printed dataIndentablePrintStream
@Deprecated public TraceMethod entry(String methodSignature)
entry(String returnType, Class clazz, String methodSignature)
or
entry(String returnType, Object object, String methodSignature)
methodSignature
- the signature of the method as string representationpublic TraceMethod entry(String returnType, Object object, String methodSignature)
TracingContext
exists for the current thread a TraceMethod
object
will be created and thereupon pushed onto the stack of a ThreadMap
.returnType
- the return type of the method as string representationobject
- the object that owns the methodmethodSignature
- the remaining method signature (without return type) inclusive parameter as string representationpublic TraceMethod entry(String returnType, Class clazz, String methodSignature)
TracingContext
exists for the current thread a TraceMethod
object
will be created and thereupon pushed onto the stack of a ThreadMap
.returnType
- the return type of the method as string representationclazz
- the class to which that method belongmethodSignature
- the remaining method signature (without return type) inclusive parameter as string representationpublic TraceMethod wayout()
public void logMessage(LogLevel logLevel, String message, Class clazz, String methodName)
logLevel
- one of the predefined levels INFO, WARNING, ERROR, FATAL and SEVEREmessage
- the to be logged messageclazz
- the originating classmethodName
- the originating methodpublic void logException(LogLevel logLevel, Throwable throwable, Class clazz, String methodName)
logLevel
- one of the predefined levels INFO, WARNING, ERROR, FATAL and SEVEREthrowable
- the to be logged throwableclazz
- the originating classmethodName
- public void initCurrentTracingContext(int debugLevel, boolean online)
debugLevel
- controls the extent of the outputonline
- a value of false delivers no output of the current thread at all whereas a value of true delivers output controlled by debugLevelpublic void initCurrentTracingContext()
public void clearCurrentTracingContext()
out()
from the current thread will
return the NullPrintStream.protected String substitute(String expression) throws AbstractTracer.Exception
expression
- the to be replaced expressionAbstractTracer.Exception
- indicates problems during the replacementprotected String formatStreamErrorState()
IndentablePrintStream
of this Tracer instance.protected String formatVersionInfo()
Copyright © 2014 Christof Reichardt. All rights reserved. (Build: 26-May-2014)