com.bbn.openmap.util
Class Debug

java.lang.Object
  extended by com.bbn.openmap.util.Debug

public abstract class Debug
extends java.lang.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.

Version:
$Revision: 1.6 $, $Date: 2004/12/08 01:10:45 $
Author:
Tom Mitchell (tmitchell@bbn.com), $Author: dietrick $

Field Summary
static boolean debugAll
          Flag to indicate whether all debug messages should get printed.
static java.lang.String debugAllToken
          The user specified flag to indicate all debugging is on.
protected static java.io.PrintStream err
          The stream where debugging error messages should go.
static java.lang.String ERROR_HEADER
           
static java.lang.String ERROR_TAIL
           
protected static boolean errorAppend
          Flag to have the errors appended to the error log.
protected static java.io.File errorFile
          The File for logging errors.
protected static java.io.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 java.io.PrintStream out
          The stream where debugging output should go.
protected static java.io.DataOutputStream outputLog
          The DataOutputStream for logging output.
 
Method Summary
static boolean debugging(java.lang.String token)
          Indicates if the debugging for the named token is on or off.
static void directErrors(java.io.File file, boolean alsoToErrStream)
          Provide a file to log errors.
static void directErrors(java.io.OutputStream os, boolean alsoToErrStream)
          Provide a DataOutputStream to log errors.
static void directErrors(java.lang.String filename, boolean append, boolean alsoToErrStream)
          Provide a file to log errors.
static void directOutput(java.io.File file, boolean alsoToOutStream)
          Provide a file to log output.
static void directOutput(java.io.OutputStream os, boolean alsoToOutStream)
          Provide a DataOutputStream to log output.
static void directOutput(java.lang.String filename, boolean append, boolean alsoToOutStream)
          Provide a file to log output.
static void error(java.lang.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 java.io.PrintStream getErrorStream()
          Accessor for the current error output stream.
static java.lang.String getMapBeanMessage()
          A reflective method to get the copyright message from the MapBean without having to actually compile the MapBean when Debug is compiled.\
static java.io.PrintStream getPrintStream()
          Accessor for the current debugging output stream.
static void init()
          Initialize debugging from the system properties.
static void init(java.applet.Applet applet, java.lang.String[] parameters)
          Initialize debugging for the given applet.
static void init(java.util.Properties p)
          Initialize debugging for an application.
static void main(java.lang.String[] args)
          main routine used in unit testing.
static void message(java.lang.String dbgToken, java.lang.String message)
          Prints message if dbgToken debugging is on.
static void output()
          println to output.
static void output(java.lang.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.
static void put(java.lang.String dbgToken)
          Installs a new debug token
static void remove(java.lang.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(java.io.PrintStream err)
          Sets the error output stream to the named stream.
static void setLog(java.io.File file, boolean alsoToStreams)
          Provide a file to log output.
static void setLog(java.io.OutputStream logStream, boolean alsoToStreams)
          Provide an output stream to log output.
static void setPrintStream(java.io.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 java.lang.String ERROR_HEADER

ERROR_TAIL

public static java.lang.String ERROR_TAIL

On

public static final boolean On
Globally enable or disable debugging.

See Also:
Constant Field Values

out

public static java.io.PrintStream out
The stream where debugging output should go. Default is System.out.


err

protected static java.io.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 java.io.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 java.io.DataOutputStream outputLog
The DataOutputStream for logging output.


errorLog

protected static java.io.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 java.lang.String debugAllToken
The user specified flag to indicate all debugging is on. Default is "all".

Method Detail

init

public static void init(java.applet.Applet applet,
                        java.lang.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(java.util.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.


debugging

public static boolean debugging(java.lang.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(java.lang.String dbgToken)
Installs a new debug token

Parameters:
dbgToken - token name

remove

public static void remove(java.lang.String dbgToken)
Rremoves a debug token

Parameters:
dbgToken - token name

message

public static void message(java.lang.String dbgToken,
                           java.lang.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(java.io.PrintStream out)
Sets the debugging output stream to the named stream.

Parameters:
out - the desired debugging output stream

getPrintStream

public static java.io.PrintStream getPrintStream()
Accessor for the current debugging output stream.

Returns:
the current debugging output stream.

directOutput

public static void directOutput(java.io.File file,
                                boolean alsoToOutStream)
Provide a file to log output. This can be in conjunction with the output 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 output

directOutput

public static void directOutput(java.lang.String filename,
                                boolean append,
                                boolean alsoToOutStream)
Provide a file to log output. This can be in conjunction with the output stream, or instead of it.

Parameters:
filename - the file to use for the error log.
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 output.

directOutput

public static void directOutput(java.io.OutputStream os,
                                boolean alsoToOutStream)
Provide a DataOutputStream to log output. This can be in conjunction with the output 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 output.

setErrorStream

public static void setErrorStream(java.io.PrintStream err)
Sets the error output stream to the named stream.

Parameters:
err - the desired error output stream

getErrorStream

public static java.io.PrintStream getErrorStream()
Accessor for the current error output stream.

Returns:
the current error output stream.

directErrors

public static void directErrors(java.io.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(java.lang.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:
filename - the file to use for the error log.
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(java.io.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(java.lang.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.

getMapBeanMessage

public static java.lang.String getMapBeanMessage()
A reflective method to get the copyright message from the MapBean without having to actually compile the MapBean when Debug is compiled.\

Returns:
MapBean message.

output

public static void output()
println to output.


output

public static void output(java.lang.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(java.io.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(java.io.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(java.lang.String[] args)
main routine used in unit testing.

Parameters:
args - none expected


Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details