com.gargoylesoftware.base.trace
public class Trace extends Object
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 $
Nested Class Summary | |
---|---|
static class | Trace.WhereAmIException An exception used to determine where the code is at any point in time. |
Field Summary | |
---|---|
static TraceChannel | err
The equivilent of "standard error" |
static String | LINE_SEPARATOR |
static TraceChannel | out
The equivilent of "standard out" |
static TraceController | TRACE_CONTROLLER |
static TraceItemDispatcher | TRACE_ITEM_DISPATCHER |
Constructor Summary | |
---|---|
Trace()
Private constructor to prevent instantiation of this class. |
Method Summary | |
---|---|
protected static void | assertNotNull(String fieldName, Object fieldValue)
Verify that the specified value is not null. |
static void | exit(int statusCode)
Shutdown all buffering and exit the VM with the specified
status code.
|
static void | flush()
Flush the trace queue. |
static TraceController | getController()
Return the controller object for the debugging stuff
|
static TraceItemDispatcher | getDispatcher() |
static void | print(TraceChannel channel, String string)
Print a line to the specified channel.
|
static void | print(String string)
Print a line to the default channel
If the channel is null then nothing will be printed. |
static void | println(TraceChannel channel, String string)
Print the line to the specified channel with a new line at the end.
|
static void | println(String string)
Print the line to the default channel with a new line at the end.
|
static void | printLines(String[] lines)
Print the specified lines to the default trace channel. |
static void | printLines(TraceChannel channel, String[] lines)
Print the specified lines to the trace channel.
|
static void | printStackTrace(TraceChannel channel, Throwable throwable)
Print the stack trace to the specified channel.
|
static void | printStackTrace(Throwable throwable)
Print the stack trace to the default channel. |
static String | throwableToString(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 void | whereAmI()
Print a stack trace to show where we came from. |
static void | whereAmI(TraceChannel channel)
Print a stack trace to show where we came from. |
Parameters: fieldName The name of the field to check fieldValue The value of the field to check
Throws: DetailedNullPointerException If fieldValue is null
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.
Returns: The controller in use.
Returns: The dispatcher
Parameters: channel The trace channel to use string The text string to write.
Parameters: string The text string to write.
Parameters: channel The trace channel to use string the string to write.
Parameters: string the string to write.
Parameters: lines The lines to print.
Parameters: channel The trace channel to use lines the lines to print.
Parameters: channel The trace channel to use throwable The exception to print
Parameters: throwable The exception to print.
Parameters: t The exception.
Returns: The resulting string.
Parameters: t The exception.
Returns: The resulting string.
Parameters: channel The trace channel to use.