## com.bbn.openmap.util
Class Debug

    java.lang.Object
      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.4.2.2 $, $Date: 2004/12/08 01:45:43 $
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 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(java.lang.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:
    `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 ouput.

### directOutput

    public static void directOutput(java.io.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(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.

### 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.

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