<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>Designof Util-Classes</name>
    <doc-version>$Date: 2003/09/23 19:54:16 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>
<P>
<EM>For more details, see the <link name="using">using</link> document/</EM>
</P>


<section>Chainable Exceptions</section>
<P>
Chainable exceptions are implemented by using a helper class to contain
the logic behind the standard exception methods.  This allows for creating
a new exception or extending one with the chainable property fairly easy.
</P>

<section>Service Provider Interface Loading</section>
<P>
The SPI framework is used by applications to, at run-time, discover
implementation classes of a service.  These implementation classes implement
a service class or interface, and are dynamically loaded and instantiated
to fulfill a role that the application requires.
</P>
<P>
The <tt>SPILoader</tt> class knows how to parse a class loader for references
to files under <tt>META-INF/services/<i>classname</i></tt>.  Multiple of
these files may be defined per JAR file or directory in the classpath,
so the <tt>SPILoader</tt> iterates through all references of this
file.
</P>
<P>
Each service file is a text file describing the class names that provide an
implementation of the service class.  Each service class must be on its own
line (whitespace is ignored), and must be declared with the fully-qualified
class name that implements the service.  Empty lines and lines beginning
with a hash mark ("#") are ignored.
</P>

<section>Throwable Parsing</section>
<P>
The Throwable Parsing classes are a wrapper around the stack
trace listing methods introduced to the <tt>java.lang.Throwable</tt>
class in JDK 1.4.  The GroboUtil classes will either use the JDK 1.4
methods (if running in JDK 1.4), or revert to parsing the output from
<tt>printStackTrace()</tt>.
</P>

<section>Class Load Helper</section>
<P>
The Class Load Helper class is a collection of utilities that contain logic
to aid the developer in writing dynamic class loading code.  There exist
many neuances behind the particulars for this, especially when dealing
with different JDK versions, and this class attempts to isolate the
developer from many of these headaches.
</P>

<section>Singleton Stores</section>
<P>
There comes a time when applications need the use of a singleton.  The
problem with static access to a singleton (or worse - a class with static
methods) is that it can be difficult to extend the functionality of said
singletons, or to swap them out with different ones.  Such a situation may
be where one process discovers an optimization that could be used, and so
the singleton could be swapped out with another to allow for faster
run times.  Another situation may be where old software references a
utility, but new or different functionality may be required by add-on
software; in order for the old software to gain this new functionality
(say, additional logging), the original singleton will need to be swapped
with the new one.
</P>
<P>
In order to support this kind of behavior, the Singleton Stores classes
were created.
</P>
</body>
</document>
