org.concord.util
Class Debug

java.lang.Object
  |
  +--org.concord.util.Debug

public class Debug

extends java.lang.Object

Debug contains useful code and constants for debugging.

There are two methods that developers are expected to use for routine debugging support during development. Assert() is used to test a condition and, if the condition fails, log the message and terminate the thread that called it. It should only be used in situations where failing the test is a catastrophic condition. Its function does NOT change between debug and release versions. The log() method will log an arbitrary string, and is conditioned on a passed in "level" integer. See the log level defintions below for information on what level to use and when.

Version:

$Revision: 1.2 $ $Date: 2001/08/31 15:43:13 $

Author:

$Author: ed $

Field Summary

static int	BENGINE
static int	BTEST
static boolean	debug
static boolean	DEBUG Debug constant.
static int	ERROR
static int	INFO
static int	NONE Constants used for the log level and in calls to log().
static int	UTIL
static int	WARNING

Constructor Summary

Debug()

Method Summary

static void	addDebugging(java.lang.String token)
static void	assert(boolean test, java.lang.String message, java.lang.Object obj) The classic assert - if the test fails, prints a message and throws an Error.
static int	getLogLevel() Get the log level.
protected static java.io.PrintWriter	getPrintWriter()
protected static java.io.PrintWriter	getPrintWriter2()
static boolean	isDebugging(java.lang.Object object, java.lang.String token)
static boolean	isDebugging(java.lang.String token)
static boolean	isPartialMatch()
static void	log(int messageLevel, java.lang.String message, java.lang.Object obj) Log a debug string to the system output if the passed in log level is LOWER than or equal to the current log level OR if the Debug log level is greater than INFO, the level passed in is INFO or less or equal to the current Debug log level.
static void	println(java.lang.String message) Print out a message to our output stream.
static void	printStackTrace(java.lang.Throwable e) Print a stack trace for the exception passed in to the logging stream.
static void	removeDebugging(java.lang.String token)
static void	setDebug(boolean value)
static void	setDebugInstance(Debug newInstance) Set the instance of Debug that we use when calling writeString() - this allows writeString() to be overridden for situations where there are no streams (e.g.
static void	setLogLevel(int level) Set the log level.
static void	setPartialMatch(boolean partial)
static void	setPrintWriter(java.io.PrintWriter pw, boolean closeWhenDone) Set the printStream to print logging output to.
static void	setPrintWriter2(java.io.PrintWriter pw2, boolean closeWhenDone) Set the printStream2 to print logging output to.
protected void	writeString(java.lang.String message, java.lang.Object obj) Send a string to our print stream for debugging purposes.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

public static final boolean DEBUG

Debug constant.

Set this to true for normal, debuggable builds.

Set this to false for release, non-debuggable builds.

When this is false, the compiler will eliminate any code wrapped in if(debug) { ... }.

debug

public static boolean debug

NONE

public static final int NONE

Constants used for the log level and in calls to log(). Note that if you need an additional level constants, just take the next one available and add it to the list with an appropriate comment. The first three log levels, NONE, ERROR and WARNING are global log levels meaning they may be used by anyone and are available in the release version. Setting Debug's log level to NONE means no log messages will be displayed, to ERROR means only ERROR level log messages will be displayed and to WARNING means that ERROR and WARNING level log messages will be displayed. The log levels that follow after the first three are for debug use only and represent areas of functionality within Symposium. Setting Debug's log level to one of these will cause only ERROR, WARNING and that level messages to be displayed, filtering out all other debug messages.

ERROR

public static final int ERROR

WARNING

public static final int WARNING

INFO

public static final int INFO

UTIL

public static final int UTIL

BTEST

public static final int BTEST

BENGINE

public static final int BENGINE

Constructor Detail

Debug

public Debug()

Method Detail

setDebug

public static void setDebug(boolean value)

addDebugging

public static void addDebugging(java.lang.String token)

removeDebugging

public static void removeDebugging(java.lang.String token)

isDebugging

public static boolean isDebugging(java.lang.Object object,
                                  java.lang.String token)

isDebugging

public static boolean isDebugging(java.lang.String token)

setPartialMatch

public static void setPartialMatch(boolean partial)

isPartialMatch

public static boolean isPartialMatch()

assert

public static final void assert(boolean test,
                                java.lang.String message,
                                java.lang.Object obj)
                         throws java.lang.Error

The classic assert - if the test fails, prints a message and throws an Error.

Parameters:

test - Boolean which is the result of the test you passed in

message - String which can be whatever you like to indicate what failed

obj - Object associated with message, normally 'this', may be null for statics

getLogLevel

public static final int getLogLevel()

Get the log level. This makes it possible for outside debugging code to also condition itself on Debug's log level;

Returns:

Current log level.

setLogLevel

public static final void setLogLevel(int level)

Set the log level.

Parameters:

level - Level to which the logging system should be set (duh).

log

public static final void log(int messageLevel,
                             java.lang.String message,
                             java.lang.Object obj)
                      throws java.lang.Error

Log a debug string to the system output if the passed in log level is LOWER than or equal to the current log level OR if the Debug log level is greater than INFO, the level passed in is INFO or less or equal to the current Debug log level. If the level passed in is set to ERROR, this method will throw a run-time exception to halt the calling thread (as this is a catastrophic error).

Parameters:

messageLevel - The logging level of this log message.

message - The String which is the message itself.

Throws:

java.lang.Error - - if the error reported is catastrophic, no one should catch this

println

public static final void println(java.lang.String message)

Print out a message to our output stream. Note that this ALWAYS writes to the output stream - it is intended to be used for start-up information etc. that is always desirable.

printStackTrace

public static final void printStackTrace(java.lang.Throwable e)

Print a stack trace for the exception passed in to the logging stream. This method should be used rather than calling exception.printStackTrace so the trace can be written to the Debug stream. Note that there is no level associated with this method as it is assumed a stack trace is always wanted regardless of the level.

Parameters:

e - Throwable - exception to print stack trace for

setDebugInstance

public static final void setDebugInstance(Debug newInstance)

Set the instance of Debug that we use when calling writeString() - this allows writeString() to be overridden for situations where there are no streams (e.g. servlets).

Parameters:

newInstance - Debug - instance of Debug (or subclass) to use

setPrintWriter

public static final void setPrintWriter(java.io.PrintWriter pw,
                                        boolean closeWhenDone)

Set the printStream to print logging output to. Output defaults to System.out initially. Closes old print stream if one exists.

Parameters:

pw - PrintWriter - new print writer, may be null

closeWhenDone - boolean - should the print writer be closed when a new one is set?

setPrintWriter2

public static final void setPrintWriter2(java.io.PrintWriter pw2,
                                         boolean closeWhenDone)

Set the printStream2 to print logging output to. Output defaults to null initially. Closes old print stream if one exists.

Parameters:

pw2 - PrintWriter - new print writer 2, may be null

closeWhenDone - boolean - should the print writer be closed when a new one is set?

getPrintWriter

protected static final java.io.PrintWriter getPrintWriter()

getPrintWriter2

protected static final java.io.PrintWriter getPrintWriter2()

writeString

protected void writeString(java.lang.String message,
                           java.lang.Object obj)

Send a string to our print stream for debugging purposes. Prepend the object's name. Remove the name qualifier on the object for better readability if that qualifier is one of the strings in the "prefixes" array (private variable). Note that this is non-static (all other methods are static) to allow it to be overridden for situations where streams are not available (e.g. servlets).

Parameters:

message - String to be output.

obj - Object whose name will be prepended to the message.