com.gargoylesoftware.base.trace

Class Trace

public class Trace extends Object

A class that provides a mechanism for logging diagnostic messages. This mechanism is significantly faster then calling System.out.println directly as the printing is done on a background thread which does not impact the performance of the application threads.

The methods for tracing are print(String), println(String) and printStackTrace(Throwable). The basic idea is that we want the trace methods to return to the working threads as quickly as possible so we put the thing to be traced on a queue. The queue is then processed by a second thread which performs all the formatting and actual output.

Trace can be configured using the TraceController class - see getController. It is possible to redirect System.out and System.err so that calling System.out.println("foo") will be the same as calling Trace.println("foo")

 Trace.getController().setOutRedirected(true);
 Trace.getController().setErrRedirected(true);
 
Calls to any of the print methods will print to a TraceChannel which in turn will print using whatever TraceWriters have been added to it. Print methods that do not take a TraceChannel will use the default channel - see setDefaultChannel

If you are using this code in a JVM prior to 1.3 then you need to read this:
Because trace lines are being processed on a second thread, there might still be trace messages in the queue when the VM exits. To solve this problem we introduce the method Trace which will shut down the second thread and then call System.exit(). If you are running on a java 1.3 VM or higher then it is not neccessary to call Trace as Trace will automatically install a shutdown hook which will do the neccessary cleanup.

Version: $Revision: 1.6 $

Author: Mike Bowler

Nested Class Summary
static classTrace.WhereAmIException
An exception used to determine where the code is at any point in time.
Field Summary
static TraceChannelerr
The equivilent of "standard error"
static StringLINE_SEPARATOR
static TraceChannelout
The equivilent of "standard out"
static TraceControllerTRACE_CONTROLLER
static TraceItemDispatcherTRACE_ITEM_DISPATCHER
Constructor Summary
Trace()
Private constructor to prevent instantiation of this class.
Method Summary
protected static voidassertNotNull(String fieldName, Object fieldValue)
Verify that the specified value is not null.
static voidexit(int statusCode)
Shutdown all buffering and exit the VM with the specified status code.
static voidflush()
Flush the trace queue.
static TraceControllergetController()
Return the controller object for the debugging stuff
static TraceItemDispatchergetDispatcher()
static voidprint(TraceChannel channel, String string)
Print a line to the specified channel.
static voidprint(String string)
Print a line to the default channel If the channel is null then nothing will be printed.
static voidprintln(TraceChannel channel, String string)
Print the line to the specified channel with a new line at the end.
static voidprintln(String string)
Print the line to the default channel with a new line at the end.
static voidprintLines(String[] lines)
Print the specified lines to the default trace channel.
static voidprintLines(TraceChannel channel, String[] lines)
Print the specified lines to the trace channel.
static voidprintStackTrace(TraceChannel channel, Throwable throwable)
Print the stack trace to the specified channel.
static voidprintStackTrace(Throwable throwable)
Print the stack trace to the default channel.
static StringthrowableToString(Throwable t)
Dump the stack trace from the specified throwable into a String.
static String[]throwableToStringArray(Throwable t)
Dump the stack trace from the specified throwable into an array of strings where each line in the trace is a separate string.
static voidwhereAmI()
Print a stack trace to show where we came from.
static voidwhereAmI(TraceChannel channel)
Print a stack trace to show where we came from.

Field Detail

err

public static final TraceChannel err
The equivilent of "standard error"

LINE_SEPARATOR

private static final String LINE_SEPARATOR

out

public static final TraceChannel out
The equivilent of "standard out"

TRACE_CONTROLLER

private static final TraceController TRACE_CONTROLLER

TRACE_ITEM_DISPATCHER

private static final TraceItemDispatcher TRACE_ITEM_DISPATCHER

Constructor Detail

Trace

private Trace()
Private constructor to prevent instantiation of this class.

Method Detail

assertNotNull

protected static final void assertNotNull(String fieldName, Object fieldValue)
Verify that the specified value is not null. If it is then throw an exception

Parameters: fieldName The name of the field to check fieldValue The value of the field to check

Throws: DetailedNullPointerException If fieldValue is null

exit

public static void exit(int statusCode)
Shutdown all buffering and exit the VM with the specified status code.

Note This is no longer needed if you are running JDK1.3 or higher as we now register a shutdown hook to disable buffering before the VM exits.

Parameters: statusCode The status code returned when the application exits.

flush

public static void flush()
Flush the trace queue.

getController

public static TraceController getController()
Return the controller object for the debugging stuff

Returns: The controller in use.

getDispatcher

static TraceItemDispatcher getDispatcher()

Returns: The dispatcher

print

public static void print(TraceChannel channel, String string)
Print a line to the specified channel. If the channel is null then nothing will be printed.

Parameters: channel The trace channel to use string The text string to write.

print

public static void print(String string)
Print a line to the default channel If the channel is null then nothing will be printed.

Parameters: string The text string to write.

println

public static void println(TraceChannel channel, String string)
Print the line to the specified channel with a new line at the end. If the channel is null then nothing will be printed.

Parameters: channel The trace channel to use string the string to write.

println

public static void println(String string)
Print the line to the default channel with a new line at the end.

Parameters: string the string to write.

printLines

public static void printLines(String[] lines)
Print the specified lines to the default trace channel.

Parameters: lines The lines to print.

printLines

public static void printLines(TraceChannel channel, String[] lines)
Print the specified lines to the trace channel. If the channel is null then nothing will be printed.

Parameters: channel The trace channel to use lines the lines to print.

printStackTrace

public static void printStackTrace(TraceChannel channel, Throwable throwable)
Print the stack trace to the specified channel. If the channel is null then nothing will be printed.

Parameters: channel The trace channel to use throwable The exception to print

printStackTrace

public static void printStackTrace(Throwable throwable)
Print the stack trace to the default channel.

Parameters: throwable The exception to print.

throwableToString

public static String throwableToString(Throwable t)
Dump the stack trace from the specified throwable into a String.

Parameters: t The exception.

Returns: The resulting string.

throwableToStringArray

public static String[] throwableToStringArray(Throwable t)
Dump the stack trace from the specified throwable into an array of strings where each line in the trace is a separate string. Additionally, expand all tabs to spaces.

Parameters: t The exception.

Returns: The resulting string.

whereAmI

public static void whereAmI()
Print a stack trace to show where we came from. It will be printed to the default channel.

whereAmI

public static void whereAmI(TraceChannel channel)
Print a stack trace to show where we came from. If the channel is null then nothing will be printed.

Parameters: channel The trace channel to use.