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

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

  • Field Details

  • Constructor Details

    • AbstractTracer

      public AbstractTracer(String name)
      Constructor expects a name for the tracer, preferably unique.
      Parameters:
      name - the name of the tracer.

  • Method Details

    • 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:

    • 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:

    • getTracePrintStream

      protected TracePrintStream getTracePrintStream()
      Derived classes may use this getter to retrieve the actual TracePrintStream.
      Returns:
      the tracePrintStream
      See Also:

    • 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:

    • 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