org.cdlib.xtf.util
Class Trace

Object
  extended by Trace

public class Trace
extends Object

The Trace class provides a mechanism for logging output messages to the console or any PrintStream or Writer. A number of output message levels are supported by this class, including errors, warnings, info messages, and debug messages. Outputting messages for any one of these levels is accomplished by passing a message string to the error(), warning(), info(), or debug() functions.

Messages may be indented to reflect the nesting of function calls by using the tab() and untab() functions. Single-line multi-part messages (where the first part is tabbed from the left, and additional parts are tacked on to the end of the line after additional processing) may be created using the more() functions. Indentation is normally two spaces per tab level, but this may be changed by setting the defaultTabSize variable.

The message level actually output by the trace system may be adjusted to allow all or some message types to be displayed. The output level for the trace system is set using the function setOutputLevel() function.

Each output line can be automatically prefixed with a timestamp by calling the printTimestamps(boolean) method. The default is to print without timestamps. When enabled, timestamps will be printed with a simple date format: YYYY-MM-DD:HH:MM:SS, but this can be changed if necessary by changing the value of the dateFormat member variable.

All output goes to the console (System.out) by default, but it can optionally be redirected to any PrintStream or Writer by calling setPrintStream(PrintStream) or setWriter(Writer) respectively.

If multiple threads use the Trace facility, the output of each will be marked with "[1]" for the first thread, "[2]" for the second, etc. (but if only one thread uses Trace, no such markers will be printed.) Trace automatically maintains a separate tab level for each thread, but the other variables, such as PrintStream/Writer, output level, etc., are static and apply to all threads.


Field Summary
private static boolean autoFlush
          True to force an immediate newline after every output
static DateFormat dateFormat
          Format to output dates in.
static int debug
          Print all messages (debug, info, errors, and warnings.)
static int defaultTabSize
          Amount to indent when tab() is called.
static int errors
          Print errors only
private static Trace firstTrace
          First trace instance ever created
static int info
          Print info messages, errors, and warnings
private static int nThreads
          Number of threads that have accessed Trace
private static int outputMask
          Current mask of which messages to output
private static int prevMsgLevel
          Previous message level
private static Trace prevTrace
          Trace instance that last wrote to the output stream
private static PrintStream printStream
          PrintStream to write to, or null to write to writer
private static boolean printTimestamps
          True to print a timestamp on each line
static int silent
          Print no messages
private static String spaces
          Used for tabbing
private  int tabCount
          Current tab level for this thread
private  int tabSize
          Amount to indent when tab() is called.
private  String threadId
          String to prefix messages from this thread with
private static WeakHashMap threadTraces
          Trace instance for the current thread
static int warnings
          Print errors and warnings
private static Writer writer
          Writer to write to, or null to write to printStream
 
Constructor Summary
private Trace()
          Private constructor -- used by getThreadTrace().
 
Method Summary
static void clearTabs()
          Resets the tab level to zero, undoing the effects of any calls to tab().
static void debug(String msg)
          Output a message at the 'debug' level.
static void debug(String msg, Object... args)
           
static void error(String msg)
          Output a message at the 'error' level.
static void error(String msg, Object... args)
           
static String getCurrentThreadId()
          Retrieve the thread identifier that is printed for the current thread.
static int getOutputLevel()
          Retrieves the current output level established by setOutputLevel(int).
static String getThreadId(Thread thread)
          Retrieve the thread identifier that is printed for messages from the specified thread.
private static Trace getThreadTrace()
          Gets a thread-specific instance of Trace.
static void info(String msg)
          Output a message at the 'info' level.
static void info(String msg, Object... args)
           
static void more(int level, String msg)
          Append more text to the previous output line if it was the same output level; if not, write the text to a new output line.
static void more(String msg)
          Append more text to the previous output line (unless of course it was suppressed).
private  void output(String msg, boolean tabbed, boolean linefeed)
          Workhorse output function -- handles tabbing, prefixing the output with a thread ID, timestamping, adding newlines, and directing to the proper output PrintStream or Writer.
static void printTimestamps(boolean flag)
          Enables or disables prefixing each output line with a timestamp.
static void setAutoFlush(boolean flag)
          Enables or disables immediate newline and flushing of each output line (note that this somewhat defeats the more() feature.)
static void setOutputLevel(int level)
          Set the level of message output.
static void setPrintStream(PrintStream pstream)
          Overrides the default output destination, System.out, with the given alternate print stream.
static void setWriter(Writer w)
          Overrides the default output destination, System.out, with the given alternate Writer.
private  void t_clearTabs()
          Internal threaded helper for clearTabs().
private  void t_debug(String msg)
          Internal threaded helper for debug(String).
private  void t_error(String msg)
          Internal threaded helper for error(String).
private  void t_info(String msg)
          Internal threaded helper for info(String).
private  void t_more(int level, String msg)
          Internal threaded helper for more(int, String).
private  void t_more(String msg)
          Internal threaded helper for more(String).
private  void t_tab()
          Internal threaded helper for tab()
private  void t_untab()
          Internal threaded helper for untab()
private  void t_warning(String msg)
          Internal threaded helper for warning(String).
static void tab()
          Indent all subsequent output lines by defaultTabSize (default 2) spaces.
static void untab()
          Undoes effect of tab(), un-indenting subsequent output lines.
static void warning(String msg)
          Output a message at the 'warning' level.
static void warning(String msg, Object... args)
           
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

silent

public static final int silent
Print no messages

See Also:
Constant Field Values

errors

public static final int errors
Print errors only

See Also:
Constant Field Values

warnings

public static final int warnings
Print errors and warnings

See Also:
Constant Field Values

info

public static final int info
Print info messages, errors, and warnings

See Also:
Constant Field Values

debug

public static final int debug
Print all messages (debug, info, errors, and warnings.)

See Also:
Constant Field Values

defaultTabSize

public static int defaultTabSize
Amount to indent when tab() is called. Default value: 2


dateFormat

public static DateFormat dateFormat
Format to output dates in. Default: yyyy-MM-dd:HH:mm:ss


threadTraces

private static final WeakHashMap threadTraces
Trace instance for the current thread


prevTrace

private static Trace prevTrace
Trace instance that last wrote to the output stream


firstTrace

private static Trace firstTrace
First trace instance ever created


nThreads

private static int nThreads
Number of threads that have accessed Trace


printStream

private static PrintStream printStream
PrintStream to write to, or null to write to writer


writer

private static Writer writer
Writer to write to, or null to write to printStream


prevMsgLevel

private static int prevMsgLevel
Previous message level


outputMask

private static int outputMask
Current mask of which messages to output


printTimestamps

private static boolean printTimestamps
True to print a timestamp on each line


autoFlush

private static boolean autoFlush
True to force an immediate newline after every output


spaces

private static final String spaces
Used for tabbing

See Also:
Constant Field Values

threadId

private String threadId
String to prefix messages from this thread with


tabCount

private int tabCount
Current tab level for this thread


tabSize

private int tabSize
Amount to indent when tab() is called.

Constructor Detail

Trace

private Trace()
Private constructor -- used by getThreadTrace(). Calculates a thread ID for this thread, used to prefix output messages.

Method Detail

setOutputLevel

public static void setOutputLevel(int level)
Set the level of message output. Messages below this level will not be printed.

Parameters:
level - One of silent, errors, warnings, info, or debug.

getOutputLevel

public static int getOutputLevel()
Retrieves the current output level established by setOutputLevel(int).


printTimestamps

public static void printTimestamps(boolean flag)
Enables or disables prefixing each output line with a timestamp. Default is disabled.


setAutoFlush

public static void setAutoFlush(boolean flag)
Enables or disables immediate newline and flushing of each output line (note that this somewhat defeats the more() feature.) Normally, a newline isn't printed until Trace can be sure that more() won't be used to add to the existing line.


tab

public static void tab()
Indent all subsequent output lines by defaultTabSize (default 2) spaces. Call untab() or clearTabs() to undo this effect.


t_tab

private void t_tab()
Internal threaded helper for tab()


untab

public static void untab()
Undoes effect of tab(), un-indenting subsequent output lines.


t_untab

private void t_untab()
Internal threaded helper for untab()


clearTabs

public static void clearTabs()
Resets the tab level to zero, undoing the effects of any calls to tab().


t_clearTabs

private void t_clearTabs()
Internal threaded helper for clearTabs().


setPrintStream

public static void setPrintStream(PrintStream pstream)
Overrides the default output destination, System.out, with the given alternate print stream.

Parameters:
pstream - Where to direct subsequent output to

setWriter

public static void setWriter(Writer w)
Overrides the default output destination, System.out, with the given alternate Writer.

Parameters:
w - Where to direct subsequent output to

getCurrentThreadId

public static String getCurrentThreadId()
Retrieve the thread identifier that is printed for the current thread.


getThreadId

public static String getThreadId(Thread thread)
Retrieve the thread identifier that is printed for messages from the specified thread.


error

public static void error(String msg)
Output a message at the 'error' level. If the output level established by setOutputLevel(int) is errors, warnings, info, or debug, the message will be printed. If the output level is silent, it will be suppressed.


error

public static void error(String msg,
                         Object... args)

t_error

private void t_error(String msg)
Internal threaded helper for error(String).


warning

public static void warning(String msg)
Output a message at the 'warning' level. If the output level established by setOutputLevel(int) is warnings, info, or debug, the message will be printed. If the output level is errors or silent, it will be suppressed.


warning

public static void warning(String msg,
                           Object... args)

t_warning

private void t_warning(String msg)
Internal threaded helper for warning(String).


info

public static void info(String msg)
Output a message at the 'info' level. If the output level established by setOutputLevel(int) is info, or debug, the message will be printed. If the output level is warnings, errors, or silent, it will be suppressed.


info

public static void info(String msg,
                        Object... args)

t_info

private void t_info(String msg)
Internal threaded helper for info(String).


debug

public static void debug(String msg)
Output a message at the 'debug' level. If the output level established by setOutputLevel(int) is debug, the message will be printed. If the output level is info, warnings, errors, or silent, it will be suppressed.


debug

public static void debug(String msg,
                         Object... args)

t_debug

private void t_debug(String msg)
Internal threaded helper for debug(String).


more

public static void more(String msg)
Append more text to the previous output line (unless of course it was suppressed).


t_more

private void t_more(String msg)
Internal threaded helper for more(String).


more

public static void more(int level,
                        String msg)
Append more text to the previous output line if it was the same output level; if not, write the text to a new output line.

Parameters:
level - Output level to write the message at (one of errors, warnings, info, or debug.
msg - Message to write

t_more

private void t_more(int level,
                    String msg)
Internal threaded helper for more(int, String).


getThreadTrace

private static Trace getThreadTrace()
Gets a thread-specific instance of Trace. If there wasn't one already, a new one is created.


output

private void output(String msg,
                    boolean tabbed,
                    boolean linefeed)
Workhorse output function -- handles tabbing, prefixing the output with a thread ID, timestamping, adding newlines, and directing to the proper output PrintStream or Writer.