com.protomatter.util
Class Debug

java.lang.Object
  |
  +--com.protomatter.util.Debug

All Implemented Interfaces:

java.io.Serializable

public class Debug

extends java.lang.Object

implements java.io.Serializable

A simple hierarchical namespace utility. Maintains a static list of names and/or patterns to match names. Dots (".") provide hierarchy markers. For instance, if you add the following patterns:

com.protomatter

com.protomatter.syslog.*

com.protomatter.util.*

com.protomatter.foo.bar.*

Then the following names would "match" the patterns if the "scanning" feature is turned on:

com.protomatter

com.protomatter.syslog

com.protomatter.syslog.xml

com.protomatter.util.other.package

If you have "scanning" turned off, then only the following names would match:

com.protomatter

And the following names would not "match" the patterns:

com.protomatterfoo

com.protomatter.foo

com.protomatter.jdbc.pool

This class is useful in debugging:

  import com.protomatter.util.Debug;
  import com.protomatter.util.StackTraceUtil;

  import com.protomatter.syslog.Channel;

  ...

  private final static Debug debug = Debug.forPackage(ThisClass.class);  

  private final static Channel channel = Channel.forPackage(ThisClass.class);  

  ...

  // three levels...  trace, debug and info
  if (debug.trace())
      channel.debug(this, "Really detailed tracing statements");

  if (debug.debug())
      channel.debug(this, "Debugging statements:  I'm here -> " + StackTraceUtil.whereAm());  

  if (debug.info())
      channel.info(this, "Information messages");

  

This can prevent expensive operations involved in debugging to be quickly bypassed in production environments by changing a configuration file instead of re-compiling.

All the work is done in the constructor, which calls the match() method. Calling the trace(), debug() or info() methods takes almost no time (return values are cached).

I've tested this operation on a 650MHz PIII Coppermine Sony Vaio laptop running RedHat Linux 7.2, kernel 2.4.9, I saw these results for timing "Debug.forName(name)":

Virtual Machine	Best Case	Middle Case	Worst Case
Classic VM (build JDK-1.2.2_012, green threads, nojit)	0.018627ms	0.076707ms	0.625373ms
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_03-b03)	0.001347ms	0.008267ms	0.08128ms
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)	0.00184ms	0.008067ms	0.07928ms
JRockit Virtual Machine (build 3.1.4-dax.appeal.se-20020319-1000) Native Threads, Generational Concurrent Garbage Collector	0.00092ms	0.006453ms	0.065147ms
Classic VM (build 1.3.1, J2RE 1.3.1 IBM build cxia32131-20020410 (JIT enabled: jitc))	0.00204ms	0.00488ms	0.039253ms

"Best Case" above is a direct match, where the name being matched is the same as one of the patterns. "Middle Case" is a search only one or two checks away from success, like matching "foo.bar.baz" against "foo.bar.*". "Worst Case" is a match that's 13 checks away. All cases had around 125 patterns in the search group. Your mileage may vary.

If you call setScan(false), then all matches will be "Best Case" but only exact matches will return true.

If disable() has been called, this method will return false immediately. If there are no patterns set, it has the same effect.

See Also:

Channel, Syslog, StackTraceUtil, SyslogXML.configure(org.jdom.Element), Serialized Form

Method Summary

static void	addDebugName(java.lang.String name) Add a name or pattern to the matching set at the "debug" level.
static void	addInfoName(java.lang.String name) Add a name or pattern to the matching set at the "info" level.
static void	addTraceName(java.lang.String name) Add a name or pattern to the matching set at the "trace" level.
static void	clear() Clear the sets of patterns and names.
boolean	debug() Does our name match anything in the list of names and patterns.
static void	disable() Disable all checks.
static void	enable() Enable checks.
static Debug	forClass(java.lang.Class someClass) Get a debug object with name of the given class.
static Debug	forName(java.lang.String name) Get a debug object with the given name.
static Debug	forPackage(java.lang.Class someClass) Get a debug object with name of the given class's package.
static java.util.Iterator	getDebugNames() Get the names and/or patterns to match at the "debug" severity.
static java.util.Iterator	getInfoNames() Get the names and/or patterns to match at the "info" severity.
java.lang.String	getName() Get the name this instance uses.
static boolean	getScan() Should we scan for matches? Default is false.
static java.util.Iterator	getTraceNames() Get the names and/or patterns to match at the "trace" severity.
boolean	info() Does our name match anything in the list of names and patterns.
void	init() Initialize this Debug instance.
static boolean	isEnabled() Determine if checks are enabled or disabled.
static void	main(java.lang.String[] args) Performance testing rig.
static void	setScan(boolean setting) Set if we scan for matches.
java.lang.String	toString() Return a human-readable representation of this object.
boolean	trace() Does our name match anything in the list of names and patterns.

Methods inherited from class java.lang.Object

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

Method Detail

init

public final void init()

Initialize this Debug instance. Each time this method is called, the name of this instance is matched against the various patterns for each severity level. This method is called by the constructor.

forClass

public static final Debug forClass(java.lang.Class someClass)

Get a debug object with name of the given class. Pass in the class com.protomatter.syslog.Channel would use the name "com.protomatter.syslog.Channel". A new instance of this class is created (and initialized) each time this method is called.

forPackage

public static final Debug forPackage(java.lang.Class someClass)

Get a debug object with name of the given class's package. Pass in the class com.protomatter.syslog.Channel would use the name "com.protomatter.syslog". If the class has no package, the name of the class is used. A new instance of this class is created (and initialized) each time this method is called.

forName

public static final Debug forName(java.lang.String name)

Get a debug object with the given name. A new instance of this class is created (and initialized) each time this method is called.

disable

public static final void disable()

Disable all checks. This effectively means that the on() and match() methods on all instances of this class will return false until the enable() method is called.

enable

public static final void enable()

Enable checks. This is the default state.

isEnabled

public static final boolean isEnabled()

Determine if checks are enabled or disabled.

trace

public final boolean trace()

Does our name match anything in the list of names and patterns. This value is cached when this object is instantiated, but is updated if the configuration is changed after this instance is created.

debug

public final boolean debug()

Does our name match anything in the list of names and patterns. This value is cached when this object is instantiated, but is updated if the configuration is changed after this instance is created.

info

public final boolean info()

Does our name match anything in the list of names and patterns. This value is cached when this object is instantiated, but is updated if the configuration is changed after this instance is created.

setScan

public static final void setScan(boolean setting)

Set if we scan for matches. Default is false. If set, we scan "up" the name hierarchy, which can be a little time consuming. It may make sense to enable, and then only allow for exact matches on names.

getScan

public static final boolean getScan()

Should we scan for matches? Default is false. If set, we scan "up" the name hierarchy, which can be a little time consuming. It may make sense to enable, and then only allow for exact matches on names.

getTraceNames

public static final java.util.Iterator getTraceNames()

Get the names and/or patterns to match at the "trace" severity.

getDebugNames

public static final java.util.Iterator getDebugNames()

Get the names and/or patterns to match at the "debug" severity.

getInfoNames

public static final java.util.Iterator getInfoNames()

Get the names and/or patterns to match at the "info" severity.

addTraceName

public static final void addTraceName(java.lang.String name)

Add a name or pattern to the matching set at the "trace" level.

addDebugName

public static final void addDebugName(java.lang.String name)

Add a name or pattern to the matching set at the "debug" level.

addInfoName

public static final void addInfoName(java.lang.String name)

Add a name or pattern to the matching set at the "info" level.

clear

public static final void clear()

Clear the sets of patterns and names.

getName

public final java.lang.String getName()

Get the name this instance uses.

toString

public final java.lang.String toString()

Return a human-readable representation of this object.

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] args)

Performance testing rig.