TracerFactory (de.christofreichardt:tracelogger 1.8.0 API)

java.lang.Object
- de.christofreichardt.diagnosis.TracerFactory

```
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.
Author:

Christof Reichardt

Nested Class Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstance
```
public static TracerFactory getInstance()
```
    Retrieves the single TracerFactory.
    
    Returns:
    
    the single TracerFactory
  - getDefaultTracer
```
public NullTracer getDefaultTracer()
```
    Returns:
    
    the defaultTracer
  - getQueueSize
```
public int getQueueSize()
```
    Returns:
    
    the size of the tracer queue
  - isQueueEnabled
```
public boolean isQueueEnabled()
```
    Returns:
    
    indicates if the tracer queue is enabled
  - getQueueTracerClassname
```
public String getQueueTracerClassname()
```
    Returns:
    
    the classname of the employed QueueTracer
  - readConfiguration
```
public void readConfiguration(File configFile)
                       throws TracerFactory.Exception,
                              FileNotFoundException
```
    Reads the given configuration file, validates it against a XML-Schema and creates the tracer pool, its mappings and the queue accordingly. This method should normally be invoked once at program start. Multiple calls with the same configuration file leads to instantiations of new tracer objects and mappings which will replace the old tracers and their mappings.
    
    Parameters:
    
    configFile - the configuration file
    
    Throws:
    
    TracerFactory.Exception - indicates a configuration problem
    
    FileNotFoundException - indicates a missing configuration file
  - readConfiguration
```
public void readConfiguration(InputStream inputStream)
                       throws TracerFactory.Exception
```
    Reads the configuration from the given InputStream.
    
    Parameters:
    
    inputStream - the input stream providing the configuration.
    
    Throws:
    
    TracerFactory.Exception - indicates a configuration problem
    
    See Also:
    
    readConfiguration(java.io.File)
  - getTracer
```
public AbstractTracer getTracer(String name)
                         throws TracerFactory.Exception
```
    Returns the pooled tracer with the given name.
    
    Parameters:
    
    name - the name of the desired tracer
    
    Returns:
    
    the pooled tracer
    
    Throws:
    
    TracerFactory.Exception - if no tracer exists with the given name
  - getTracer
```
public AbstractTracer getTracer(Thread thread)
```
    Returns the mapped tracer for the given thread. The given Thread object is used as key to a map. If no tracer can be found within the map for the given Thread the configuration will be searched for the thread's name. That is initially the resolution is based on thread names (prior to program execution no threads do exist but someone may know the to be used thread names). If there isn't an entry for a given Thread but the name of the thread has been encountered before (thread names aren't unique) a NullTracer will be returned.
    
    Parameters:
    
    thread - the thread for which a tracer is searched
    
    Returns:
    
    the mapped tracer for the given thread
  - getCurrentPoolTracer
```
public AbstractTracer getCurrentPoolTracer()
```
    Returns the mapped tracer for the current thread.
    
    Returns:
    
    the mapped tracer for the current thread
    
    See Also:
    
    getTracer(java.lang.Thread)
  - reset
```
public void reset()
```
    Clears the pool, the mappings and the queue.
  - openPoolTracer
```
public void openPoolTracer()
```
    Opens all pooled tracers.
  - closePoolTracer
```
public void closePoolTracer()
```
    Closes all pooled tracers.
  - takeTracer
```
public QueueTracer<?> takeTracer()
```
    Takes the tracer from the head of the deque. If the deque is empty the methods blocks until a tracer will become available. By default a QueueTracer wrapping a NullTracer will be (non-blocking) delivered.
    
    Returns:
    
    the tracer from the head of the deque
  - offerTracer
```
protected boolean offerTracer(QueueNullTracer queueNullTracer)
```
    Required for symmetrical reasons. The code used for debugging (enabled queue) and for production (disabled queue) should not differ. In the latter case takeTracer() delivers by default a QueueNullTracer (without blocking) which must not be enqueued again. Hence this method will simply discard the given QueueNullTracer.
    
    Parameters:
    
    queueNullTracer - a previously taken QueueTracer
    
    Returns:
    
    always false
    
    See Also:
    
    offerTracer(de.christofreichardt.diagnosis.QueueTracer)
  - offerTracer
```
protected boolean offerTracer(QueueTracer<?> tracer)
```
    Used to enqueue a tracer which has been previously retrieved by a call to takeTracer().
    
    Parameters:
    
    tracer - the to be enqueued tracer
    
    Returns:
    
    indicates if the tracer has been enqueued (true) or has been discarded (false)
  - openQueueTracer
```
public boolean openQueueTracer()
```
    Tries to open all enqueued QueueTracer.
    
    Returns:
    
    true if all configured tracers has been opened, false otherwise
  - closeQueueTracer
```
public boolean closeQueueTracer()
```
    Tries to close all enqueued QueueTracer.
    
    Returns:
    
    true if all configured tracers has been closed, false otherwise
  - getCurrentQueueTracer
```
public QueueTracer<?> getCurrentQueueTracer()
```
    Returns the QueueTracer for the current thread. If no one was found a QueueNullTracer will be returned.
    
    Returns:
    
    the QueueTracer for the current thread

Class TracerFactory

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getDefaultTracer

getQueueSize

isQueueEnabled

getQueueTracerClassname

readConfiguration

readConfiguration

getTracer

getTracer

getCurrentPoolTracer

reset

openPoolTracer

closePoolTracer

takeTracer

offerTracer

offerTracer

openQueueTracer

closeQueueTracer

getCurrentQueueTracer