abbot
Class Log

java.lang.Object
  abbot.Log

public class Log
extends Object

Various logging, assertion, and debug routines. Typical usage is to include the following code

   public static void main(String[] args) {
  args = Log.init(args)
  ...
   }
   

at an application's main entry point. This way the Log class can remove its options from the full set passed into the application. See the Log.init method for initialization options.

General usage notes on public functions:

• warn(String)
  Programmer warnings; things that you think shouldn't be happening or indicate something might be wrong. Warnings typically mean "Something happened that I didn't expect would happen".

• log(String)
  Important information that might be needed for later reference; things the user or debugger might be interested in. By default, all messages go here. Logs are made available so that the customer may provide us with an accurate record of software activity.
  All warnings and failed assertions are written to the log. Debug statements are also written to log in non-release code.

• debug(String)
  Any messages which might be useful for debugging.

Per-class stack trace depth can be specified when adding a class, e.g. classname[:stack-depth].

Extraction of the stack trace and logging to file are performed on a separate thread to minimize performance impact due to filesystem delays. Use setSynchronous(false) if you want the output to be asynchronous with program execution.

Author:

twall@users.sf.net

Field Summary

static int	FULL_STACK Mnemonic to print all lines of a stack trace.
static int	NO_STACK No stack, just a message.

Constructor Summary

protected

Log() No instantiations.

Method Summary

static void	addDebugClass(Class class1) Indicate that debug messages should be output for the given class.
static void	addDebugClass(String className) Indicate the class name[:depth] to add to debug output.
static void	addDebugClass(String className, int depth) Indicate that debug messages should be output for the given class.
static void	clearDebugClasses() Resets the lists of classes to debug and not debug to be empty, and turns debugAll off.
static void	close()
static void	debug(String event) Print a debug message.
static void	debug(String event, int lines) Print a debug message with the given number of stack lines.
static void	debug(String m, Throwable e) Issue a debug statement regarding the given Throwable.
static void	debug(Throwable thr) Use this to display debug output for expected or common exceptions.
(package private) static void	flush()
(package private) static int	getClassStackDepth(String cname)
static String	getHostName()
static PrintStream	getLog()
static String	getLogFilename()
static String	getStack(int lines) Retrieve the given number of lines of the current stack, as a string.
static String	getStack(int lines, Throwable thr) Retrieve the given number of lines of stack from the given Throwable, as a string.
static String	getStack(Throwable t) Retrieve the full stack from the given Throwable, as a string.
static String	getSystemInfo()
static String[]	init(String[] args) Debug/log initialization, presumably from the command line.
static void	initLogging(String filename) Enable log output to the given file.
static boolean	isClassDebugEnabled(Class cls)
static boolean	isClassDebugEnabled(String className)
static void	log(String message) Log a message.
static void	log(String message, Throwable thr) Log an exception with a description.
static void	log(Throwable thr) Log an exception.
static boolean	loggingInitialized() Is log output enabled?
static void	removeDebugClass(Class class1) Indicate that debug messages should no longer be output for the given class.
static void	removeDebugClass(String className) Indicate that the given class should NOT be debugged (assuming --debug all)
static void	setDebugStackDepth(int depth) Sets the debug stack depth to the given amount
static void	setDestination(PrintStream ps) Enable log output to the given PrintStream.
static void	setEchoToConsole(boolean b) Set whether messages are echoed to the console in addition to the log.
static void	setShowThreads(boolean b) Set whether to display the current thread of execution.
static void	setSynchronous(boolean b) Set whether log output is synchronous with program execution.
static void	warn(String message) Issue a programmer warning, which will include the source line of the warning.
static void	warn(String message, int lines) Issue a programmer warning, which will include the source line of the warning, and a stack trace with up to the given number of lines.
static void	warn(String message, Throwable e) Issue a programmer warning, which will include the source line of the warning.
static void	warn(Throwable thr) Issue a programmer warning, which will include the source line of the original thrown object.

Methods inherited from class java.lang.Object

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

Field Detail

FULL_STACK

public static final int FULL_STACK

Mnemonic to print all lines of a stack trace.

See Also:

Constant Field Values

NO_STACK

public static final int NO_STACK

No stack, just a message.

See Also:

Constant Field Values

Constructor Detail

Log

protected Log()

No instantiations.

Method Detail

init

public static String[] init(String[] args)

Debug/log initialization, presumably from the command line.
Recognized options:

        --debug all | className[:depth] | *.partialClassName[:depth]
        --no-debug className | *.partialClassName
        --log 
        --no-timestamp
        --enable-warnings
        --show-threads
        --stack-depth 
        --exception-depth 
        

loggingInitialized

public static boolean loggingInitialized()

Is log output enabled?

getHostName

public static String getHostName()

getLogFilename

public static String getLogFilename()

getLog

public static PrintStream getLog()

initLogging

public static void initLogging(String filename)

Enable log output to the given file. A filename of "-" means stdout.

setDestination

public static void setDestination(PrintStream ps)

Enable log output to the given PrintStream.

getSystemInfo

public static String getSystemInfo()

setDebugStackDepth

public static void setDebugStackDepth(int depth)

Sets the debug stack depth to the given amount

clearDebugClasses

public static void clearDebugClasses()

Resets the lists of classes to debug and not debug to be empty, and turns debugAll off.

removeDebugClass

public static void removeDebugClass(String className)

Indicate that the given class should NOT be debugged (assuming --debug all)

addDebugClass

public static void addDebugClass(Class class1)

Indicate that debug messages should be output for the given class.

removeDebugClass

public static void removeDebugClass(Class class1)

Indicate that debug messages should no longer be output for the given class.

addDebugClass

public static void addDebugClass(String className)

Indicate the class name[:depth] to add to debug output.

addDebugClass

public static void addDebugClass(String className,
                                 int depth)

Indicate that debug messages should be output for the given class.

isClassDebugEnabled

public static boolean isClassDebugEnabled(Class cls)

isClassDebugEnabled

public static boolean isClassDebugEnabled(String className)

getClassStackDepth

static int getClassStackDepth(String cname)

debug

public static void debug(String event)

Print a debug message.

debug

public static void debug(String event,
                         int lines)

Print a debug message with the given number of stack lines.

debug

public static void debug(Throwable thr)

Use this to display debug output for expected or common exceptions.

debug

public static void debug(String m,
                         Throwable e)

Issue a debug statement regarding the given Throwable.

getStack

public static String getStack(int lines)

Retrieve the given number of lines of the current stack, as a string.

getStack

public static String getStack(Throwable t)

Retrieve the full stack from the given Throwable, as a string.

getStack

public static String getStack(int lines,
                              Throwable thr)

Retrieve the given number of lines of stack from the given Throwable, as a string.

warn

public static void warn(String message)

Issue a programmer warning, which will include the source line of the warning.

warn

public static void warn(String message,
                        Throwable e)

Issue a programmer warning, which will include the source line of the warning.

warn

public static void warn(String message,
                        int lines)

Issue a programmer warning, which will include the source line of the warning, and a stack trace with up to the given number of lines.

warn

public static void warn(Throwable thr)

Issue a programmer warning, which will include the source line of the original thrown object.

log

public static void log(Throwable thr)

Log an exception.

log

public static void log(String message,
                       Throwable thr)

Log an exception with a description.

log

public static void log(String message)

Log a message.

flush

static void flush()

close

public static void close()

setSynchronous

public static void setSynchronous(boolean b)

Set whether log output is synchronous with program execution.

setShowThreads

public static void setShowThreads(boolean b)

Set whether to display the current thread of execution.

setEchoToConsole

public static void setEchoToConsole(boolean b)

Set whether messages are echoed to the console in addition to the log.