Package de.christofreichardt.diagnosis

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

    • 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

      • isOnline

        public boolean isOnline​(String threadName)
        Indicates if some particular thread is configured to be online.
        Parameters:
        threadName - the name of the thread
        Returns:
        true if the thread is configured to be online

      • getLevel

        public int getLevel​(String threadName)
        Returns the configured debug level - that is the stack size - up until trace messages will be printed for a particular thread
        Parameters:
        threadName - the name of the thread
        Returns:
        the configured debug level

      • getNullPrintStream

        protected NullPrintStream getNullPrintStream()
        A replacement for /dev/null.
        Returns:
        the nullPrintStream

      • 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()

      • 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

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

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

      • 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