public class TracerFactory extends Object
A factory and holder of tracers. Tracers will be created according to a given (XML-)configuration. So long as no configuration has been read
some methods provide a default tracer. This default tracer traces nothing and routes log messages to the core logging facilities of the Java platform,
see java.util.logging and JDKLoggingRouter
.
The configuration file consists of four main sections. You can put tracer into a pool and access them by name. Second you may redefine the default tracer. Third you can map threads on tracer and subsequently access the primary tracer for a given thread. Or you may configure a blocking queue of tracer for multi-threading environments for which you cannot control thread creation. Consider for example the following definitions:
<?xml version="1.0" encoding="UTF-8" ?> <TraceConfig xmlns="http://www.christofreichardt.de/java/tracer"> <Pool> <TraceLogger name="ExampleTracer" class="de.christofreichardt.diagnosis.file.FileTracer"> <LogDir>./log/</LogDir> <AutoFlush>true</AutoFlush> <BufSize>1024</BufSize> <Limit>1048576</Limit> <Context> <Thread name="main"> <Online>true</Online> <DebugLevel>5</DebugLevel> </Thread> </Context> </TraceLogger> </Pool> <Map> <Threads> <Thread name="main"> <TraceLogger ref="ExampleTracer" /> </Thread> </Threads> </Map> </TraceConfig>
The definitions above make use of the first and the third section. A FileTracer
has been configured. Its outputfile is located at
./log/ExampleTracer.log. The tracer is in autoflush mode, that is every time an observed method is popped from the stack the output stream will be flushed.
The tracer will back up its file when it reaches the size of one MebiByte (1024*1024 Byte). The 'ExampleTracer' is interested in output from the
main-Thread up to a stack size of five. Note that this is not the call stack of the Java Virtual Machine. You may put only methods you are interested in on
a separate stack managed by a TracingContext
. The main-Thread has been mapped on the 'ExampleTracer'. Therefore you may invoke a convenience
method to retrieve the tracer for this thread. Assuming you put the configuration file into ./config/ExampleConfig.xml, the TracerFactory can be
configured and used like this from the main-Thread:
File configFile = new File("." + File.separator + "config" + File.separator + "ExampleConfig.xml"); TracerFactory.getInstance().readConfiguration(configFile); final AbstractTracer tracer = TracerFactory.getInstance().getCurrentPoolTracer(); 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(); // the configured tracing context will be used foo.bar(); // this will generate output } finally { tracer.close(); }
The generated output can be found at ./log/ExampleTracer.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
This approach makes sense if you control the creation of threads. Keep in mind that the Java Virtual Machine doesn't guarantee the uniqueness of thread names.
That is when you invoke TracerFactory.getInstance().getCurrentPoolTracer()
from another thread called 'main' later on,
you will get the default tracer which routes log messages (but not the tracing output) to the JDK logger.
Modifier and Type | Class and Description |
---|---|
static class |
TracerFactory.Exception
Base exception class for all exceptional situations within the context of the TracerFactory
|
protected class |
TracerFactory.Queue
If appropriately configured it enables access to a blocking deque of tracers.
|
Modifier and Type | Method and Description |
---|---|
void |
closePoolTracer()
Closes all pooled tracers.
|
boolean |
closeQueueTracer()
Tries to close all enqueued QueueTracer.
|
AbstractTracer |
getCurrentPoolTracer()
Returns the mapped tracer for the current thread.
|
QueueTracer<?> |
getCurrentQueueTracer()
Returns the QueueTracer for the current thread.
|
NullTracer |
getDefaultTracer() |
static TracerFactory |
getInstance()
Retrieves the single TracerFactory.
|
int |
getQueueSize() |
String |
getQueueTracerClassname() |
AbstractTracer |
getTracer(String name)
Returns the pooled tracer with the given name.
|
AbstractTracer |
getTracer(Thread thread)
Returns the mapped tracer for the given thread.
|
boolean |
isQueueEnabled() |
protected boolean |
offerTracer(QueueNullTracer queueNullTracer)
Required for symmetrical reasons.
|
protected boolean |
offerTracer(QueueTracer<?> tracer)
Used to enqueue a tracer which has been previously retrieved by a call to
takeTracer() . |
void |
openPoolTracer()
Opens all pooled tracers.
|
boolean |
openQueueTracer()
Tries to open all enqueued QueueTracer.
|
void |
readConfiguration(File configFile)
Reads the given configuration file, validates it against a XML-Schema and creates the tracer pool, its mappings and the queue accordingly.
|
void |
readConfiguration(InputStream inputStream)
Reads the configuration from the given InputStream.
|
void |
reset()
Clears the pool, the mappings and the queue.
|
QueueTracer<?> |
takeTracer()
Takes the tracer from the head of the deque.
|
public static TracerFactory getInstance()
public NullTracer getDefaultTracer()
public int getQueueSize()
public boolean isQueueEnabled()
public String getQueueTracerClassname()
public void readConfiguration(File configFile) throws TracerFactory.Exception, FileNotFoundException
configFile
- the configuration fileTracerFactory.Exception
FileNotFoundException
public void readConfiguration(InputStream inputStream) throws TracerFactory.Exception
inputStream
- the input stream providing the configuration.TracerFactory.Exception
readConfiguration(java.io.File)
public AbstractTracer getTracer(String name) throws TracerFactory.Exception
name
- the name of the desired tracerTracerFactory.Exception
- if no tracer exists with the given namepublic AbstractTracer getTracer(Thread thread)
thread
- the thread for which a tracer is searchedpublic AbstractTracer getCurrentPoolTracer()
getTracer(java.lang.Thread)
public void reset()
public void openPoolTracer()
public void closePoolTracer()
public QueueTracer<?> takeTracer()
protected boolean offerTracer(QueueNullTracer queueNullTracer)
takeTracer()
delivers by default a QueueNullTracer (without blocking) which must not be enqueued again. Hence this method will simply discard
the given QueueNullTracer.queueNullTracer
- a previously taken QueueTracerofferTracer(de.christofreichardt.diagnosis.QueueTracer)
protected boolean offerTracer(QueueTracer<?> tracer)
takeTracer()
.tracer
- the to be enqueued tracerpublic boolean openQueueTracer()
public boolean closeQueueTracer()
public QueueTracer<?> getCurrentQueueTracer()
Copyright © 2014 Christof Reichardt. All rights reserved. (Build: 26-May-2014)