edu.rice.cs.plt.debug
Class DebugUtil

java.lang.Object
  edu.rice.cs.plt.debug.DebugUtil

public final class DebugUtil
extends java.lang.Object

A collection of utility fields and methods to facilitate code-embedded debugging and logging

Field Summary

static Log	debug A globally-accessible debugging log, declared in the spirit of System.out.
static Log	error A globally-accessible error log, declared in the spirit of System.out.

Method Summary

static Log	assertEmptyLog()
static boolean	check(boolean assertion) An alternative to the built-in assert statement that treats the assertion as an expression rather than a statement.
static Log	fileLog(java.io.File f)
static Log	fileLog(java.lang.String filename)
static java.lang.StackTraceElement	getCaller() Get the stack trace element representing the method immediately preceding the current method on the stack.
static void	initializeLogs() Initialize debug and error based on the descriptors appearing in system properties plt.debug.log and plt.error.log.
static java.lang.Runnable	logExceptions(Log l, java.lang.Runnable r) Wrap a Runnable in a try-catch block that logs all caught RuntimeExceptions.
static <T> Runnable1<T>	logExceptions(Log l, Runnable1<? super T> r) Wrap a Runnable1 in a try-catch block that logs all caught RuntimeExceptions.
static <T1,T2> Runnable2<T1,T2>	logExceptions(Log l, Runnable2<? super T1,? super T2> r) Wrap a Runnable2 in a try-catch block that logs all caught RuntimeExceptions.
static <T1,T2,T3> Runnable3<T1,T2,T3>	logExceptions(Log l, Runnable3<? super T1,? super T2,? super T3> r) Wrap a Runnable3 in a try-catch block that logs all caught RuntimeExceptions.
static <T1,T2,T3,T4> Runnable4<T1,T2,T3,T4>	logExceptions(Log l, Runnable4<? super T1,? super T2,? super T3,? super T4> r) Wrap a Runnable4 in a try-catch block that logs all caught RuntimeExceptions.
static void	logThreadStatus(Log log, long... delays) Log the status (name, state, stack, etc.), of the current thread after a delay.
static void	logThreadStatus(Log log, java.lang.Thread thread, long... delays) Log the status (name, state, stack, etc.), of the given thread after a delay.
static java.lang.Runnable	logThrowables(Log l, java.lang.Runnable r) Wrap a Runnable in a try-catch block that logs all caught Throwables.
static <T> Runnable1<T>	logThrowables(Log l, Runnable1<? super T> r) Wrap a Runnable1 in a try-catch block that logs all caught Throwables.
static <T1,T2> Runnable2<T1,T2>	logThrowables(Log l, Runnable2<? super T1,? super T2> r) Wrap a Runnable2 in a try-catch block that logs all caught Throwables.
static <T1,T2,T3> Runnable3<T1,T2,T3>	logThrowables(Log l, Runnable3<? super T1,? super T2,? super T3> r) Wrap a Runnable3 in a try-catch block that logs all caught Throwables.
static <T1,T2,T3,T4> Runnable4<T1,T2,T3,T4>	logThrowables(Log l, Runnable4<? super T1,? super T2,? super T3,? super T4> r) Wrap a Runnable4 in a try-catch block that logs all caught Throwables.
static Log	makeLog(java.lang.String descriptor, java.lang.String defaultName) Produce a Log corresponding to the given descriptor.
static LogSink	makeLogSink(java.lang.String descriptor, java.lang.String defaultName) Produce a LogSink corresponding to the given descriptor.
static Log	popupLog(java.lang.String name)
static Log	remoteTreeLog(java.lang.String name)
static LogSink	remoteTreeLogSink(java.lang.String name) Create an RMILogSink that passes messages to a remote TreeLogSink with exitOnClose set to true.
static Log	systemErrLog()
static Log	systemErrLog(java.lang.String charsetName)
static Log	systemOutLog()
static Log	systemOutLog(java.lang.String charsetName)
static Log	voidLog()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

public static volatile Log debug

A globally-accessible debugging log, declared in the spirit of System.out. This log is intended to record information that would be useful in a debugging session, but that is too detailed for typical program executions. By default, its value is a VoidLog; logging behavior may be changed by setting the system property plt.debug.log, or by directly setting this field (it is declared volatile so that changes take immediate effect in all threads).

See Also:

initializeLogs()

error

public static volatile Log error

A globally-accessible error log, declared in the spirit of System.out. This log is intended to record errors that should be noted, but that do not require the propagation of an exception. By default, its value is a VoidLog; logging behavior may be changed by setting the system property plt.error.log, or by directly setting this field (it is declared volatile so that changes take immediate effect in all threads).

See Also:

initializeLogs()

Method Detail

initializeLogs

public static void initializeLogs()

Initialize debug and error based on the descriptors appearing in system properties plt.debug.log and plt.error.log. This method is run automatically when the DebugUtil class is loaded. If desired, it may be re-invoked at any time.

See Also:

makeLog(java.lang.String, java.lang.String), makeLogSink(java.lang.String, java.lang.String)

makeLog

public static Log makeLog(java.lang.String descriptor,
                          java.lang.String defaultName)

Produce a Log corresponding to the given descriptor. If the descriptor is a valid sink descriptor, a StandardLog is returned; otherwise, a VoidLog is returned. ("void" is a convenient special case of an invalid sink descriptor.)

See Also:

makeLogSink(java.lang.String, java.lang.String)

makeLogSink

public static LogSink makeLogSink(java.lang.String descriptor,
                                  java.lang.String defaultName)

Produce a LogSink corresponding to the given descriptor. The descriptor is a sink type, with additional support for asynchronous sinks, string parameters, filters, and splitting.

• <descriptor> := <descriptor>, <descriptor> | [~] <single-descriptor> <filter>
• <single-descriptor> := <type> [:<parameter>] | (<descriptor>)
• <type> := System.out | stdout | System.err | stderr | file | assert | popup | tree
• <parameter> := <an arbitrary string parameter for the given sink type>
• <filter> := ( +<loc-filter> | -<loc-filter> | +'<thread-filter>' | -'<thread-filter>' )*
• <loc-filter> := <the prefix of fully-qualified method names to include or exclude>
• <thread-filter> := <a substring of thread names to include or exclude>

Examples:

• "stdout, stderr": Log to both System.out and System.err.
• "tree, ~file": Log synchronously to a remoteTreeLogSink(java.lang.String) and asynchronously to a file (named after defaultName and with location determined by the plt.log.working.dir and user.dir properties).
• "file:pkg1.txt +pkg1, file:pkg2.txt +pkg2": Log messages from package pkg1 to file pkg1.txt and messages from package pkg2 to file pkg2.txt.
• "(stdout:'UTF-8', stderr:'UTF-8') -'Foo'": Log all messages except those coming from threads with "Foo" in their names to both System.out and System.err, encoded as UTF-8 text. Note that apostrophes may be used to prevent interpreting delimiters appearing within the sink's argument string.
• "assert +com -com.pkg1 -com.pkg2": Assert that no logging messages come from locations in subpackages of "com", but allowing an exception for messages from "com.pkg1" and "com.pkg2".

The set of supported types can be extended by defining the property plt.log.factory to point to a static method. The method must have a signature matching the following (any method name can be used): LogSink factoryMethod(String type, String arg, String defaultName). The arg parameter will be an empty string if none is provided by the descriptor. This factory method is invoked before reverting to the default interpretations; to delegate to the default behavior, the method should return null.

voidLog

public static Log voidLog()

assertEmptyLog

public static Log assertEmptyLog()

systemOutLog

public static Log systemOutLog()

systemOutLog

public static Log systemOutLog(java.lang.String charsetName)
                        throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

systemErrLog

public static Log systemErrLog()

systemErrLog

public static Log systemErrLog(java.lang.String charsetName)
                        throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

fileLog

public static Log fileLog(java.lang.String filename)

fileLog

public static Log fileLog(java.io.File f)

popupLog

public static Log popupLog(java.lang.String name)

remoteTreeLog

public static Log remoteTreeLog(java.lang.String name)

remoteTreeLogSink

public static LogSink remoteTreeLogSink(java.lang.String name)

Create an RMILogSink that passes messages to a remote TreeLogSink with exitOnClose set to true.

check

public static boolean check(boolean assertion)

An alternative to the built-in assert statement that treats the assertion as an expression rather than a statement. If assertions are enabled and the argument is false, this method will fail; in any case, the value of the argument is returned. This allows code to be conditionally executed when assertions are disabled. For example: if (DebugUtil.check(x != null)) x.useMethod(). (Of course, unlike built-in assertions, calls to check() will always be executed, with their associated overhead, whether assertions are enabled or not.)

getCaller

public static java.lang.StackTraceElement getCaller()

Get the stack trace element representing the method immediately preceding the current method on the stack. This gives methods the (dangerous, but useful for debugging) ability to "see" who is calling them.

Throws:

java.lang.IllegalStateException - If the stack information is not available

logThreadStatus

public static void logThreadStatus(Log log,
                                   long... delays)

Log the status (name, state, stack, etc.), of the current thread after a delay. Invokes Log.logValues(java.lang.String[], java.lang.Object...) on the given log. Delayed logging events are scheduled on a daemon thread, and so may not run if program execution terminates first.

Parameters:

log - Log to write to.

delays - A set of delays (in milliseconds) after which the thread should be logged. If empty, the status is logged immediately. Otherwise, the status is logged after each specified delay.

logThreadStatus

public static void logThreadStatus(Log log,
                                   java.lang.Thread thread,
                                   long... delays)

Log the status (name, state, stack, etc.), of the given thread after a delay. Invokes Log.logValues(java.lang.String[], java.lang.Object...) on the given log. Delayed logging events are scheduled on a daemon thread, and so may not run if program execution terminates first.

Parameters:

thread - The thread to observe.

log - Log to write to.

delays - A set of delays (in milliseconds) after which the thread should be logged. If empty, the status is logged immediately. Otherwise, the status is logged after each specified delay.

logExceptions

public static java.lang.Runnable logExceptions(Log l,
                                               java.lang.Runnable r)

Wrap a Runnable in a try-catch block that logs all caught RuntimeExceptions.

logThrowables

public static java.lang.Runnable logThrowables(Log l,
                                               java.lang.Runnable r)

Wrap a Runnable in a try-catch block that logs all caught Throwables.

logExceptions

public static <T> Runnable1<T> logExceptions(Log l,
                                             Runnable1<? super T> r)

Wrap a Runnable1 in a try-catch block that logs all caught RuntimeExceptions.

logThrowables

public static <T> Runnable1<T> logThrowables(Log l,
                                             Runnable1<? super T> r)

Wrap a Runnable1 in a try-catch block that logs all caught Throwables.

logExceptions

public static <T1,T2> Runnable2<T1,T2> logExceptions(Log l,
                                                     Runnable2<? super T1,? super T2> r)

Wrap a Runnable2 in a try-catch block that logs all caught RuntimeExceptions.

logThrowables

public static <T1,T2> Runnable2<T1,T2> logThrowables(Log l,
                                                     Runnable2<? super T1,? super T2> r)

Wrap a Runnable2 in a try-catch block that logs all caught Throwables.

logExceptions

public static <T1,T2,T3> Runnable3<T1,T2,T3> logExceptions(Log l,
                                                           Runnable3<? super T1,? super T2,? super T3> r)

Wrap a Runnable3 in a try-catch block that logs all caught RuntimeExceptions.

logThrowables

public static <T1,T2,T3> Runnable3<T1,T2,T3> logThrowables(Log l,
                                                           Runnable3<? super T1,? super T2,? super T3> r)

Wrap a Runnable3 in a try-catch block that logs all caught Throwables.

logExceptions

public static <T1,T2,T3,T4> Runnable4<T1,T2,T3,T4> logExceptions(Log l,
                                                                 Runnable4<? super T1,? super T2,? super T3,? super T4> r)

Wrap a Runnable4 in a try-catch block that logs all caught RuntimeExceptions.

logThrowables

public static <T1,T2,T3,T4> Runnable4<T1,T2,T3,T4> logThrowables(Log l,
                                                                 Runnable4<? super T1,? super T2,? super T3,? super T4> r)

Wrap a Runnable4 in a try-catch block that logs all caught Throwables.