de.fhg.igd.earth.model.input.shapefile
Class Debug

java.lang.Object
  de.fhg.igd.earth.model.input.shapefile.Debug

public abstract class Debug

extends Object

An abstract class that presents a static interface for debugging output. It also provides a way to direct output into a log. There are two types of output - the regular output information, and the error information, and they can be handled separately. There are two differences between the two - the error file only gets created if there is an error, and the error messages have a header and a tail surrounding the messages, making them easier to spot. If the output and error file are set to be the same (setLogFile()), then that file is created automatically, regardless of anything being put into it.

Debugging output is turned on or off by system properties for applications, or parameters for applets.

A programmer can use code like the following:

 if (Debug.debugging("foo")) {
     System.out.println("Got " + nbytes + " bytes of data.");
 }
 

The message gets printed when the application is run with -Ddebug.foo or when the applet gets run with:

<param name=debug.foo value=>

The special token debug.all turns on all debugging for both applets and applications.

Field Summary

private static Hashtable	dbgTable
static boolean	debugAll Flag to indicate whether all debug messages should get printed.
static String	debugAllToken The user specified flag to indicate all debugging is on.
private static String	debugTokenHeader
protected static PrintStream	err The stream where debugging error messages should go.
static String	ERROR_HEADER
static String	ERROR_TAIL
protected static boolean	errorAppend Flag to have the errors appended to the error log.
protected static File	errorFile The File for logging errors.
protected static DataOutputStream	errorLog The DataOutputStream for logging errors.
protected static boolean	notifyErr The flag for whether the err stream should still be notified if logging errors.
protected static boolean	notifyOut The flag for whether the output stream should still be notified if logging output.
static boolean	On Globally enable or disable debugging.
static PrintStream	out The stream where debugging output should go.
protected static DataOutputStream	outputLog The DataOutputStream for logging output.

Constructor Summary

private

Debug() Don't allow construction, all methods are static.

Method Summary

static boolean	debugging(String token) Indicates if the debugging for the named token is on or off.
static void	directErrors(File file, boolean alsoToErrStream) Provide a file to log errors.
static void	directErrors(OutputStream os, boolean alsoToErrStream) Provide a DataOutputStream to log errors.
static void	directErrors(String filename, boolean append, boolean alsoToErrStream) Provide a file to log errors.
static void	directOutput(File file, boolean alsoToOutStream) Provide a file to log output.
static void	directOutput(OutputStream os, boolean alsoToOutStream) Provide a DataOutputStream to log output.
static void	directOutput(String filename, boolean append, boolean alsoToOutStream) Provide a file to log output.
static void	error(String errorString) Handle error messages, buy writing them to an error log, if that has been set up, and/or to the error stream, if requested.
static PrintStream	getErrorStream() Accessor for the current error output stream.
static PrintStream	getPrintStream() Accessor for the current debugging output stream.
static void	init() Initialize debugging from the system properties.
static void	init(Applet applet, String[] parameters) Initialize debugging for the given applet.
static void	init(Properties p) Initialize debugging for an application.
static void	main(String[] args) main routine used in unit testing.
static void	message(String dbgToken, String message) Prints message if dbgToken debugging is on.
static void	output() println to output.
static void	output(String outputString) Handle output messages, buy writing them to an output log, if that has been set up, and/or to the output stream, if requested.
private static void	postInit() Common inits, regardless of applet or application.
static void	put(String dbgToken) Installs a new debug token
static void	remove(String dbgToken) Rremoves a debug token
static void	resetOutput() Reset the logging to the output.
static void	sampleUsage() Dummy function to illustrate usage of the debugging class.
static void	setErrorStream(PrintStream err) Sets the error output stream to the named stream.
static void	setLog(File file, boolean alsoToStreams) Provide a file to log output.
static void	setLog(OutputStream logStream, boolean alsoToStreams) Provide an output stream to log output.
static void	setPrintStream(PrintStream out) Sets the debugging output stream to the named stream.

Methods inherited from class java.lang.Object

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

Field Detail

ERROR_HEADER

public static String ERROR_HEADER

ERROR_TAIL

public static String ERROR_TAIL

On

public static final boolean On

Globally enable or disable debugging.

See Also:

Constant Field Values

out

public static PrintStream out

The stream where debugging output should go. Default is System.out.

err

protected static PrintStream err

The stream where debugging error messages should go. Default is System.err. Use the function Debug.error to write to it, in case you also want to direct output to a file.

errorFile

protected static File errorFile

The File for logging errors.

notifyOut

protected static boolean notifyOut

The flag for whether the output stream should still be notified if logging output.

notifyErr

protected static boolean notifyErr

The flag for whether the err stream should still be notified if logging errors.

outputLog

protected static DataOutputStream outputLog

The DataOutputStream for logging output.

errorLog

protected static DataOutputStream errorLog

The DataOutputStream for logging errors.

errorAppend

protected static boolean errorAppend

Flag to have the errors appended to the error log.

debugAll

public static boolean debugAll

Flag to indicate whether all debug messages should get printed. This is shorthand for defining all the debug symbols.

debugAllToken

public static String debugAllToken

The user specified flag to indicate all debugging is on. Default is "all".

dbgTable

private static Hashtable dbgTable

debugTokenHeader

private static String debugTokenHeader

Constructor Detail

Debug

private Debug()

Don't allow construction, all methods are static.

Method Detail

init

public static void init(Applet applet,
                        String[] parameters)

Initialize debugging for the given applet. Applets must pass an array of parameters because the applet Parameters list cannot be accessed in whole, only queried. The parameters list looks something like this:

 String[] debugTokens = {
  "debug.debug",      // com.bbn.openmap.Debug
  "debug.openmap",    // com.bbn.openmap.client.OpenMap
  "debug.mappanel",   // com.bbn.openmap.awt.MapPanel
  "debug.awt",        // com.bbn.openmap.awt.*
  "debug.map",        // com.bbn.openmap.Map
  "debug.layer",      // com.bbn.openmap.Layer
  "debug.proj",       // com.bbn.openmap.proj.*
  "debug.spec",       // com.bbn.openmap.spec.*
  "debug.env"     // com.bbn.openmap.Environment
  };
 

Parameters:

applet - The applet

parameters - The debugging flags to look for in the applet's parameters list

init

public static void init(Properties p)

Initialize debugging for an application. Debugging symbols are detected in the given properties list, and must have the form "debug.X", where X is a debug token used in the application.

Parameters:

p - A properties list, usually System.getProperties()

init

public static void init()

Initialize debugging from the system properties.

postInit

private static void postInit()

Common inits, regardless of applet or application.

debugging

public static boolean debugging(String token)

Indicates if the debugging for the named token is on or off.

Parameters:

token - a candidate token

Returns:

true if debugging is on, false otherwise.

put

public static void put(String dbgToken)

Installs a new debug token

Parameters:

dbgToken - token name

remove

public static void remove(String dbgToken)

Rremoves a debug token

Parameters:

dbgToken - token name

message

public static void message(String dbgToken,
                           String message)

Prints message if dbgToken debugging is on. NOTE, WARNING!: this is a potentially expensive method if you pass a message String composed of many concatenated pairs. For example, like:
`onceStr+" "+uponStr+" a "+timeStr+", "+ ... +"\nThe end."'
Instead you should do:

  if (Debug.debugging(dbgToken)) {
      Debug.output(onceStr+" "+uponStr+" a "+timeStr+", "+ ... +"\nThe end.");
  }
 

Parameters:

dbgToken - a token to be tested by debugging()

message - a message to be printed

setPrintStream

public static void setPrintStream(PrintStream out)

Sets the debugging output stream to the named stream.

Parameters:

out - the desired debugging output stream

getPrintStream

public static PrintStream getPrintStream()

Accessor for the current debugging output stream.

Returns:

the current debugging output stream.

directOutput

public static void directOutput(File file,
                                boolean alsoToOutStream)

Provide a file to log output. This can be in conjunction with the ouput stream, or instead of it. Will overwrite the file, if it exists.

Parameters:

file - the file to use for the error log.

alsoToOutStream - true if the out stream should still provide output, in addition to logging the ouput.

directOutput

public static void directOutput(String filename,
                                boolean append,
                                boolean alsoToOutStream)

Provide a file to log output. This can be in conjunction with the ouput stream, or instead of it.

Parameters:

append - if true, log the output at the end of the file, instead of the beginning.

alsoToOutStream - true if the out stream should still provide output, in addition to logging the ouput.

directOutput

public static void directOutput(OutputStream os,
                                boolean alsoToOutStream)

Provide a DataOutputStream to log output. This can be in conjunction with the ouput stream, or instead of it.

Parameters:

os - the OutputStream that's handling outputlogging.

alsoToOutStream - true if the out stream should still provide output, in addition to logging the ouput.

setErrorStream

public static void setErrorStream(PrintStream err)

Sets the error output stream to the named stream.

getErrorStream

public static PrintStream getErrorStream()

Accessor for the current error output stream.

Returns:

the current error output stream.

directErrors

public static void directErrors(File file,
                                boolean alsoToErrStream)

Provide a file to log errors. This can be in conjunction with the errorstream, or instead of it.

Parameters:

file - the file to use for the error log.

alsoToErrStream - true if the err stream should still provide output, in addition to logging the errors.

directErrors

public static void directErrors(String filename,
                                boolean append,
                                boolean alsoToErrStream)

Provide a file to log errors. This can be in conjunction with the errorstream, or instead of it.

Parameters:

append - if true, log the output at the end of the file, instead of the beginning.

alsoToErrStream - true if the err stream should still provide output, in addition to logging the errors.

directErrors

public static void directErrors(OutputStream os,
                                boolean alsoToErrStream)

Provide a DataOutputStream to log errors. This can be in conjunction with the errorstream, or instead of it.

Parameters:

os - the DataOutputStream handling error logging.

alsoToErrStream - true if the err stream should still provide output, in addition to logging the errors.

error

public static void error(String errorString)

Handle error messages, buy writing them to an error log, if that has been set up, and/or to the error stream, if requested. The special thing about error output is that the error is framed with a header and a tail, hopefully to make it easier for someone to spot in the log.

Parameters:

errorString - the string to write as an error.

output

public static void output()

println to output.

output

public static void output(String outputString)

Handle output messages, buy writing them to an output log, if that has been set up, and/or to the output stream, if requested.

Parameters:

outputString - the string to write as output.

setLog

public static void setLog(File file,
                          boolean alsoToStreams)

Provide a file to log output. This can be in conjunction with the streams, or instead of them. This basically sets the output log and the error log to be the same thing.

Parameters:

file - the file to use for the error log.

alsoToStreams - true if the streams should still provide output, in addition to logging the output.

setLog

public static void setLog(OutputStream logStream,
                          boolean alsoToStreams)

Provide an output stream to log output. This can be in conjunction with the streams, or instead of them. This basically sets the output log and the error log to be the same thing.

Parameters:

logStream - the output stream for output.

alsoToStreams - true if the streams should still provide output, in addition to logging the output.

resetOutput

public static void resetOutput()

Reset the logging to the output.

sampleUsage

public static void sampleUsage()

Dummy function to illustrate usage of the debugging class.

main

public static void main(String[] args)

main routine used in unit testing.