Class Trace
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 TraceWriter
s have been
added to it. Print methods that do not take a TraceChannel
will use the default channel - see
TraceController.setDefaultChannel(TraceChannel)
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 exit(int)
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 exit(int)
as Trace will automatically install a shutdown hook which will do the
neccessary cleanup.
- Version:
- $Revision: 1.6 $
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
An exception used to determine where the code is at any point in time. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final TraceChannel
The equivilent of "standard error"private static final String
static final TraceChannel
The equivilent of "standard out"private static final TraceController
private static final TraceItemDispatcher
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Trace()
Private constructor to prevent instantiation of this class. -
Method Summary
Modifier and TypeMethodDescriptionprotected static final 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
Return the controller object for the debugging stuff(package private) static TraceItemDispatcher
static void
print
(TraceChannel channel, String string) Print a line to the specified channel.static void
Print a line to the default channel If the channel is null then nothing will be printed.static void
printLines
(TraceChannel channel, String[] lines) Print the specified lines to the trace channel.static void
printLines
(String[] lines) Print the specified lines to the default trace channel.static void
println
(TraceChannel channel, String string) Print the line to the specified channel with a new line at the end.static void
Print the line to the default channel with a new line at the end.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
Dump the stack trace from the specified throwable into a String.static String[]
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.
-
Field Details
-
out
The equivilent of "standard out" -
err
The equivilent of "standard error" -
LINE_SEPARATOR
-
TRACE_ITEM_DISPATCHER
-
TRACE_CONTROLLER
-
-
Constructor Details
-
Trace
private Trace()Private constructor to prevent instantiation of this class.
-
-
Method Details
-
print
Print a line to the specified channel. If the channel is null then nothing will be printed.- Parameters:
channel
- The trace channel to usestring
- The text string to write.
-
print
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
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 usestring
- the string to write.
-
println
Print the line to the default channel with a new line at the end.- Parameters:
string
- the string to write.
-
printStackTrace
Print the stack trace to the specified channel. If the channel is null then nothing will be printed.- Parameters:
channel
- The trace channel to usethrowable
- The exception to print
-
printStackTrace
Print the stack trace to the default channel.- Parameters:
throwable
- The exception to print.
-
printLines
Print the specified lines to the default trace channel.- Parameters:
lines
- The lines to print.
-
printLines
Print the specified lines to the trace channel. If the channel is null then nothing will be printed.- Parameters:
channel
- The trace channel to uselines
- the lines to print.
-
whereAmI
public static void whereAmI()Print a stack trace to show where we came from. It will be printed to the default channel. -
whereAmI
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.
-
throwableToStringArray
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.
-
throwableToString
Dump the stack trace from the specified throwable into a String.- Parameters:
t
- The exception.- Returns:
- The resulting string.
-
getController
Return the controller object for the debugging stuff- Returns:
- The controller in use.
-
getDispatcher
- Returns:
- The dispatcher
-
flush
public static void flush()Flush the trace queue. -
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.
-
assertNotNull
protected static final void assertNotNull(String fieldName, Object fieldValue) throws DetailedNullPointerException Verify that the specified value is not null. If it is then throw an exception- Parameters:
fieldName
- The name of the field to checkfieldValue
- The value of the field to check- Throws:
DetailedNullPointerException
- If fieldValue is null
-