idebug
Class Context

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

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class Context

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

Context is the data structure that holds the information that is relevent to debugging on a per-thread and a per- threadgroup basis.

Each thread within a program is either in a debugging state or it is not. To signal that it is in the debugging state, that thread should do the following (perhaps in an initDebug() method):

1. Create a new Context object for that thread. E.g. Context debugContext = new Context(); All of the following method calls are applied to this object, unless otherwise noted.
2. Call the turnOn(); to turn debugging on for this thread.
3. Add any new debugging categories specific to that thread with one or more of the addCategory() methods.
4. If this thread is only interested in the debugging output from a specific set of classes, the addClass() methods can be used to specify specific methods of interest. Note that you'll likely want to prefix the series of "class additions" with a removeClass(Thread.currentThread(), "*"); to flush the context of the class narrowing/widening.
5. Set the debug level that the thread is interested in with one of the setLevel() methods.

Now your thread has a valid debugging context, encapsulated in its Context object. This object is then passed to the Debug class via the addContext() method so that the debugging runtime system knows the threads context.

Version:

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

Author:

Joseph R. Kiniry

See Also:

Debug, DebugConstants, Serialized Form

Constructor Summary

Context(DebugConstants c, DebugOutput d)
The standard constructor.

Method Summary

boolean	addCategory(java.lang.String category, int level) Adds a category to the database of legal debugging categories for the owner thread.
void	addClass(java.lang.Class classRef) Adds a class to this Context's database of classes that have debugging enabled.
void	addClass(java.lang.String className) Adds a class to this Context's database of classes that have debugging enabled.
java.lang.Object	clone() Used to clone a Context for another thread.
boolean	containsCategory(java.lang.String category)
boolean	containsClass(java.lang.Class classRef)
boolean	containsClass(java.lang.String className)
int	getCategoryLevel(java.lang.String category)
int	getLevel()
DebugOutput	getOutputInterface()
java.lang.Thread	getThread()
boolean	isOn()
java.util.Enumeration	listCategories()
java.util.Enumeration	listClasses() Returns an enumeration that is the list of classes that have debugging enabled in this Context.
boolean	removeCategory(java.lang.String category) Removes a category from the database of legal debugging categories for the owner thread.
void	removeClass(java.lang.Class classRef) Removes a class from this Context's database of classes that have debugging enabled.
void	removeClass(java.lang.String className) Removes a class from this Context's database of classes that have debugging enabled.
void	setLevel(int l) Set a new debugging level for the owning thread.
void	turnOff() Turns off debugging facilities for the owner thread.
void	turnOn() Turns on debugging facilities for the owner thread.
boolean	validLevel(int l)

Methods inherited from class java.lang.Object

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

Constructor Detail

Context

public Context(DebugConstants c,
               DebugOutput d)

The standard constructor. The thread that is constructing the context is the "owning thread". All calls to this context will be recognized only in the context of the original constructing thread.

The constructor initializes all the static data-structures used by the Context class. Note that the initCategories() method is automatically called as necessary to initialize the default categories database of the Context class.

Parameters:

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

d - an implementation of DebugOutput that defines the semantics of debugging output.

Method Detail

clone

public java.lang.Object clone()

Used to clone a Context for another thread. Should be called only by the thread that is going to use/modify the context.

Overrides:

clone in class java.lang.Object

Returns:

the clone of the Context.

getThread

public java.lang.Thread getThread()

Returns:

the thread that owns this context.

turnOn

public void turnOn()

Turns on debugging facilities for the owner thread. Note that if you do not turnOff() debugging for this thread before it becomes in active in the system, it will not be garbage collected, since it is referenced by the Context object.

turnOff

public void turnOff()

Turns off debugging facilities for the owner thread. Note that if you do not turnOff debugging for this thread before it becomes in active in the system, it will not be garbage collected, since it is referenced by the Context object.

isOn

public boolean isOn()

Returns:

a boolean indicating if any debugging is turned on.

addCategory

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

Adds a category to the database of legal debugging categories for the owner thread. Once a category exists in the database, its debugging level cannot be changed without removing and re-adding the category to the database.

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 from the database of legal debugging categories for the owner thread.

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)

Parameters:

category - is the category to lookup.

Returns:

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

getCategoryLevel

public int getCategoryLevel(java.lang.String category)

Parameters:

category - is the category to lookup.

Returns:

the level of the category provided it is in the category database of this context.

listCategories

public java.util.Enumeration listCategories()

Returns:

an enumeration that is the list of per-thread debugging categories that are currently in this Context's category database. A zero-length enumeration will be returned if there are not categories defined in the database as of yet.

See Also:

Hashtable.elements()

containsClass

public boolean containsClass(java.lang.String className)

Parameters:

className - the name of the class to check.

Returns:

a boolean indicating that this Context's database of classes contains the specified class.

containsClass

public boolean containsClass(java.lang.Class classRef)

Parameters:

classRef - the class to check.

Returns:

a boolean indicating that this Context's database of classes contains the specified class.

addClass

public void addClass(java.lang.Class classRef)

Adds a class to this Context's 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 to this Context's database of classes that have debugging enabled. Note that a class of "*" means that all classes will now have debugging enabled for the owning thread. 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 from this Context's database of classes that have debugging enabled.

Parameters:

classRef - the class to remove from this Context's table of classes that have debugging enabled.

removeClass

public void removeClass(java.lang.String className)

Removes a class from this Context's database of classes that have debugging enabled. 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 class to remove from this Context's table of classes that have debugging enabled.

listClasses

public java.util.Enumeration listClasses()

Returns an enumeration that is the list of classes that have debugging enabled in this Context.

Returns:

an enumeration that is the list of the classes that currently have debugging enabled (they are in the class database) for the owning thread. Returns a zero-length enumeration if there are no enabled classes.

See Also:

Hashtable.elements()

setLevel

public void setLevel(int l)

Set a new debugging level for the owning thread.

Parameters:

l - the new debugging level.

getLevel

public int getLevel()

Returns:

the current debugging level for the owning thread.

getOutputInterface

public DebugOutput getOutputInterface()

Returns:

the DebugOutput for the owning thread.

validLevel

public boolean validLevel(int l)

Parameters:

l - the level to check.

Returns:

a flag indicating if the provided level is valid.