Protomatter Software v1.1.8

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:

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)":

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

Protomatter Software v1.1.8
Copyright 1998-2002 Nate Sammons

Protomatter Software v1.1.8 http://protomatter.sourceforge.net/1.1.8