idebug
Class Debug

java.lang.Object
  |
  +--idebug.Debug

All Implemented Interfaces:

java.lang.Cloneable

public class Debug

extends java.lang.Object

implements java.lang.Cloneable

Debug is the core class of the IDebug debugging facilities.

The Debug class is used as the central facility for configuring debugging for a component.

All assertions are handled in the Assert class, all logging is accomplished via the DebugOutput class, and all system monitoring and statistics gathering takes place via the Collect class.

This debug package is meant to help, in general, produce high quality, high confidence, code.

The Debug facility is non-static. The first thing your component or application needs to do is construct a new Debug object. If you wish to install an alternate implementation of the debugging constants (i.e. categories, levels, error messages, etc.), pass your implementation of DebugConstants to the constructor of Debug.

Each thread that calls the Debug class has, potentially, a different context. Elements of this context include a notion of current message level, message types, classes currently under inspection, and whether debugging is turned on or off.

Threads create new debugging contexts by constructing a Context object and calling its methods. This context is then passed to the Debug object to change the current global debugging context at runtime.

In brief, the Debug class is normally used in the following manner. A more detailed discussion of the use of this class can be found in the full documentation for the package. See the IDebug package's main index for more information.

Each thread needs to construct a debugging context (see the Context class for details) to detail its specific debugging needs. After creating a valid debugging context, encapsulated in the Context object, the object is passed to this class (Debug) via the addContext() method so that the debugging runtime system knows the thread's context. Note that the debug runtime keeps a reference to the passed Context, it does not make a copy of it. Thus, you can modify the Context (change debugging levels, add new thread-specific categories, etc.) after the context is installed and changes will be noted immediately by the debug runtime.

Finally, you have to direct the output of the debugging runtime. This is accomplished by constructing an implementation of the DebugOutput interface, e.g. ConsoleOutput. This object is then passed to your Debug object via the Debug.setOutputInterface() method.

You're ready to rock and roll. Call debug.getAssert() to get a reference to your debug runtime's Assert object. Finally, if you chose not to install your own implementation of DebugConstants, call debug.getDebugConstants() to get a reference to your debug constants.

Then, simply use assert.assert(), the print(), println() of your DebugOutput and/or Utilities.dumpStackSafe() methods in your code as necessary.

Note that all class-specific debugging is additive and reductive. You can either remove all classes from the debugging table then add classes one by one, or you can add all potential classes then remove them one by one at this time. Meaning, when you perform an add of "*", you are not adding all classes currently defined in this VM; you are adding all classes currently defined and all classes that might ever be defined in this VM.

Version:

$Revision: 2146 $ $Date: 2005-02-13 16:54:27 +0000 (Sun, 13 Feb 2005) $

Author:

Joseph R. Kiniry

Field Summary

DebugOutput

debugOutputInterface The class used by this thread to control debugging output device.

Constructor Summary

Debug()
Construct a new Debug class.

Debug(DebugConstants dc, Collect c)
Construct a new Debug class.

Method Summary

boolean	addCategory(java.lang.String category, int level) Adds a category to the database of legal debugging categories.
void	addClass(java.lang.Class classRef) Adds a class the the class-global database of classes that have debugging enabled.
void	addClass(java.lang.String className) Adds a class the the class-global database of classes that have debugging enabled.
boolean	addContext(Context debugContext) Adds a context to the the class-global database of threads that have debugging context.
java.lang.Object	clone()
boolean	containsCategory(java.lang.String category) Returns a boolean indicating if a category is in the class-global category database.
Assert	getAssert()
Collect	getCollect()
Context	getContext(java.lang.Thread thread) Get the context for a specific thread.
DebugConstants	getDebugConstants()
int	getLevel() Returns the current class-global debugging level.
DebugOutput	getOutputInterface()
boolean	isOff() Returns a boolean indicating if any debugging is turned off.
boolean	isOff(java.lang.Thread thread) Returns a boolean indicating whether any debugging facilities are turned off for a particular thread.
boolean	isOn() Returns a boolean indicating if any debugging is turned on.
boolean	isOn(java.lang.Thread thread) Returns a boolean indicating whether any debugging facilities are turned on for a particular thread.
java.util.Enumeration	listCategories() Returns an Enumeration that is the list of class-global debugging categories that are currently in the category database.
java.util.Enumeration	listClasses() Returns an Enumeration that is the list of class-global classes that have debugging enabled.
java.util.Enumeration	listThreads() Returns an Enumeration that is the list of class-global threads that have debugging enabled.
boolean	removeCategory(java.lang.String category) Removes a category to the database of legal debugging categories.
void	removeClass(java.lang.Class classRef) Removes a class the the class-global database of classes that have debugging enabled.
void	removeClass(java.lang.String className) Removes a class the the class-global database of classes that have debugging enabled.
boolean	removeContext(Context debugContext) Removes a context from the the class-global database of threads that have debugging context.
boolean	setLevel(int level) Set a new class-global debugging level.
void	setOutputInterface(DebugOutput d) Set the global output interface to a new DebugOutput.
void	turnOff() Turns off class-global debugging facilities.
void	turnOn() Turns on class-global debugging facilities.

Methods inherited from class java.lang.Object

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

Field Detail

debugOutputInterface

public transient DebugOutput debugOutputInterface

The class used by this thread to control debugging output device. All global debugging messages will use this interface for output.

Constructor Detail

Debug

public Debug()

Construct a new Debug class. Note that the method setOutputInterface need be called on the newly constructed Debug object before it can be used.

Debug

public Debug(DebugConstants dc,
             Collect c)

Construct a new Debug class. Note that the method setOutputInterface need be called on the newly constructed Debug object before it can be used.

Parameters:

dc - an implementation of the DebugConstants interface that defines the semantics of this debug context.

c - an implementation of the Collect class.

See Also:

SimpleCollect

Method Detail

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

setOutputInterface

public void setOutputInterface(DebugOutput d)

Set the global output interface to a new DebugOutput.

Parameters:

d - the new output interface.

getAssert

public Assert getAssert()

Returns:

the Assert object associated with this Debug object.

getCollect

public Collect getCollect()

Returns:

the Collect object associated with this Debug object.

getOutputInterface

public DebugOutput getOutputInterface()

Returns:

the DebugOutput corresponding to the invoking thread or, if that thread has no interface, the global output interface.

getDebugConstants

public DebugConstants getDebugConstants()

Returns:

the DebugConstants for this Debug object.

isOn

public boolean isOn()

Returns a boolean indicating if any debugging is turned on.

Returns:

a boolean indicating if any debugging is turned on.

isOn

public boolean isOn(java.lang.Thread thread)

Returns a boolean indicating whether any debugging facilities are turned on for a particular thread.

Parameters:

thread - is the thread that we are interested in.

Returns:

a boolean indicating whether any debugging facilities are turned on for a particular thread.

isOff

public boolean isOff()

Returns a boolean indicating if any debugging is turned off.

Returns:

a boolean indicating if any debugging is turned on.

isOff

public boolean isOff(java.lang.Thread thread)

Returns a boolean indicating whether any debugging facilities are turned off for a particular thread.

Parameters:

thread - is the thread that we are interested in.

Returns:

a boolean indicating whether any debugging facilities are turned off for a particular thread.

turnOn

public void turnOn()

Turns on class-global debugging facilities.

turnOff

public void turnOff()

Turns off class-global debugging facilities.

addCategory

public boolean addCategory(java.lang.String category,
                           int level)

Adds a category to the database of legal debugging categories. Once a category exists in the database, its debugging level cannot be changed.

Parameters:

category - the category to add to the global set of categories.

level - the debugging level associated with the passed category.

Returns:

a boolean indicating if the category was sucessfully added to the database. A false indicates either the category was already in the database at a different level or the parameters were invalid.

removeCategory

public boolean removeCategory(java.lang.String category)

Removes a category to the database of legal debugging categories.

Parameters:

category - the category to remove.

Returns:

a boolean indicating if the category was sucessfully removed from the database. A false indicates that the parameters were invalid.

containsCategory

public boolean containsCategory(java.lang.String category)

Returns a boolean indicating if a category is in the class-global category database.

Parameters:

category - is the category to lookup.

Returns:

a boolean indicating if a category is in the class-global category database.

listCategories

public java.util.Enumeration listCategories()

Returns an Enumeration that is the list of class-global debugging categories that are currently in the category database.

Returns:

an Enumeration that is the list of class-global debugging categories that are currently in the category database.

See Also:

Hashtable.elements()

addClass

public void addClass(java.lang.Class classRef)

Adds a class the the class-global database of classes that have debugging enabled.

Parameters:

classRef - the class to add to the global table of classes that have debugging enabled.

addClass

public void addClass(java.lang.String className)

Adds a class the the class-global database of classes that have debugging enabled. Note that a class of "*" means that all classes will now have debugging enabled. There is no way to "undo" such a command short of manually adding the individual classes back to the database. (Or, equivalently, removing the complement.)

Parameters:

className - the name of the class to add.

removeClass

public void removeClass(java.lang.Class classRef)

Removes a class the the class-global database of classes that have debugging enabled.

Parameters:

classRef - the class to remove.

removeClass

public void removeClass(java.lang.String className)

Removes a class the the class-global database of classes that have debugging enabled. Removes a class from a database of debugging-enabled classes. Note that a class of "*" means that all classes will be removed and debugging disabled. There is no way to "undo" such a command.

Parameters:

className - the name of the class to remove.

getContext

public Context getContext(java.lang.Thread thread)

Get the context for a specific thread.

Parameters:

thread - the thread that we are interested in.

Returns:

the Context corresponding to thread, or null if no such context exists.

addContext

public boolean addContext(Context debugContext)

Adds a context to the the class-global database of threads that have debugging context.

Parameters:

debugContext - is the context that we are interested in adding.

Returns:

a boolean indicating if the context was added to the database sucessfully or that the thread was already in the database. A false indicates that the context was invalid.

removeContext

public boolean removeContext(Context debugContext)

Removes a context from the the class-global database of threads that have debugging context.

Parameters:

debugContext - is the context that we are interested in removing.

Returns:

a boolean indicating if the context was removed from the database sucessfully or that the thread was not in the database at all. A false indicates that the context was invalid or not in the table.

listClasses

public java.util.Enumeration listClasses()

Returns an Enumeration that is the list of class-global classes that have debugging enabled.

Returns:

an Enumeration that is the list of class-global classes that currently have debugging enabled (they are in the class database). Returns a null if a null is passed, otherwise a zero-length Enumeration will be returned if there is no information on the thread at all.

See Also:

Hashtable.elements()

setLevel

public boolean setLevel(int level)

Set a new class-global debugging level.

Parameters:

level - the new debugging level.

Returns:

a boolean indicating whether the level change succeeded. The only reason why a setLevel might fail is if the level passed is out of range.

getLevel

public int getLevel()

Returns the current class-global debugging level.

Returns:

the current class-global debugging level.

listThreads

public java.util.Enumeration listThreads()

Returns an Enumeration that is the list of class-global threads that have debugging enabled.

Returns:

an Enumeration that is the list of class-global threads that currently have debugging enabled (they are in the thread database).

See Also:

Hashtable.keys()