<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>Using Util-Classes</name>
    <doc-version>$Date: 2003/09/29 21:10:37 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<section name="top">Contents</section>
<OL>
    <LI><A HREF="#spi">Service Provider Interface Loading</A></LI>
    <LI><A HREF="#chain">Chainable Exceptions</A></LI>
    <LI><A HREF="#tparse">Throwable Parsing</A></LI>
    <LI><A HREF="#clh">Class Load Helper</A></LI>
    <LI><A HREF="#sstore">Singleton Stores</A></LI>
    <LI><A HREF="#mstore">Multiple Stores</A></LI>
</OL>

<section name="spi">Service Provider Interface Loading</section>
<P><A HREF="#top"><I>Back to top</I></A></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>
</P>
<P>
The <tt>SPILoader</tt> class is used by the
<tt>net.sourceforge.groboutils.autodoc.v1.AutoDoc</tt> class, so I'll
review how that class uses the <tt>SPILoader</tt> to gain pluggable runtime
loading of services.
</P>
<P>
AutoDoc does not directly reference the SPILoader, but rather uses the
class <tt>SPISingletonStore</tt> to load and handle singleton instances.
This <tt>SPISingletonStore</tt>, in turn, uses the <tt>SPILoader</tt> to
collect the singletons.  The singleton store uses the SPI loader with
this bit of code (this.baseClass refers to the class that all service class
implementations must, well, implement):
</P>
<P>
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 97:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter"> 98:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter"> 99:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">/**</SPAN>
<SPAN CLASS="gutterH">100:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">*</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">Add</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">a</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">set</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">of</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">SPIs</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">from</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">the</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">given</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">class</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">loader</SPAN><SPAN CLASS="syntax2">.</SPAN>
<SPAN CLASS="gutter">101:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax2">*/</SPAN>
<SPAN CLASS="gutter">102:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">public</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax8">void</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">addSPI</SPAN>(<SPAN CLASS="syntax125"> </SPAN>ClassLoader<SPAN CLASS="syntax125"> </SPAN>cl<SPAN CLASS="syntax125"> </SPAN>)
<SPAN CLASS="gutter">103:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">throws</SPAN><SPAN CLASS="syntax125"> </SPAN>IOException
<SPAN CLASS="gutter">104:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">{</SPAN>
<SPAN CLASS="gutterH">105:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>SPILoader<SPAN CLASS="syntax125"> </SPAN>spil<SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">=</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">new</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">SPILoader</SPAN>(<SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax4">this</SPAN>.baseClass,<SPAN CLASS="syntax125"> </SPAN>cl<SPAN CLASS="syntax125"> </SPAN>);
<SPAN CLASS="gutter">106:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN>
<SPAN CLASS="gutter">107:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax6">while</SPAN><SPAN CLASS="syntax125"> </SPAN>(spil.<SPAN CLASS="syntax9">hasNext</SPAN>())
<SPAN CLASS="gutter">108:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">{</SPAN>
<SPAN CLASS="gutter">109:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax9">addSingleton</SPAN>(<SPAN CLASS="syntax125"> </SPAN>spil.<SPAN CLASS="syntax9">nextProvier</SPAN>()<SPAN CLASS="syntax125"> </SPAN>);
<SPAN CLASS="gutterH">110:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">}</SPAN>
<SPAN CLASS="gutter">111:</SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax125"> </SPAN><SPAN CLASS="syntax11">}</SPAN>
<SPAN CLASS="gutter">112:</SPAN><SPAN CLASS="syntax11">}</SPAN>
</PRE>
Thus, the <tt>SPILoader</tt> can be used like an enumeration or iterator.
</P>
<P>
The <tt>SPILoader</tt> finds the files in the <tt>META-INF/services</tt>
directory that has the same name as the service class.  It loads each
file found, parses it, and loads the corresponding class.  If the
class is assignable to the service class, then it is instantiated with
the default constructor, and returned.
</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>
<P>
Yes, there can be multiple service files for a particular service class!
How?  By having each file in a different JAR file which is in the classpath.
So, if someone adds multiple JAR files, each containing its own service
file (and, thus, their own service class implementations), then all will
be returned.  Note, however, that JDK 1.1 does not implement this behavior
(it wasn't introduced until JDK 1.2).
</P>

<section name="chain">Chainable Exceptions</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The Chainable Exception classes allow for a non-JDK 1.4+ application to
implement chainable exceptions.  Chainable exceptions are exceptions which
"recast" another exception.  For example, a common chore in the Apache
Ant tasks goes something like this:
<!--
    try {
        f = new FileWriter( myFile );
    } catch (IOException ioe) {
        throw new BuildException( ioe );
    }
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter">   1:</SPAN>    <SPAN CLASS="syntax8">try</SPAN> <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   2:</SPAN>        f <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">FileWriter</SPAN>( myFile );
<SPAN CLASS="gutter">   3:</SPAN>    <SPAN CLASS="syntax18">}</SPAN> <SPAN CLASS="syntax8">catch</SPAN> (IOException ioe) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   4:</SPAN>        <SPAN CLASS="syntax8">throw</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">BuildException</SPAN>( ioe );
<SPAN CLASS="gutterH">   5:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
</PRE>
Note that the developer wraps the <tt>IOException</tt> inside the
<tt>BuildException</tt>, recasting the exception to a different type.  The
<tt>BuildException</tt> class contains logic to store the embedded exception
and display the embedded exception's stack trace on calls to
<tt>BuildException.printStackTrace()</tt>.
</P>

<P>
The Chainable Exception classes has two methodologies available: extend
the <tt>ChainableException</tt> class, or use the
<tt>ChainableExceptionHelper</tt> class to make any exception chainable.
</P>

<P>
Extending the <tt>ChainableException</tt> class is much like extending
an <tt>Exception</tt>:
<!--
public class MyException extends ChainableException {
    public MyException() {
        super();
    }
    
    
    public MyException( String message ) {
        super( message );
    }
    
    
    public MyException( Throwable cause ) {
        super( cause );
    }
    
    
    public MyException( Throwable cause, String message ) {
        super( message, cause );
    }
    
    
    public MyException( String message, Throwable cause ) {
        super( message, cause );
    }
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter">   1:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyException <SPAN CLASS="syntax8">extends</SPAN> ChainableException <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   2:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   3:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter">   4:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">   5:</SPAN>    
<SPAN CLASS="gutter">   6:</SPAN>    
<SPAN CLASS="gutter">   7:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   8:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter">   9:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  10:</SPAN>    
<SPAN CLASS="gutter">  11:</SPAN>    
<SPAN CLASS="gutter">  12:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  13:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( cause );
<SPAN CLASS="gutter">  14:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  15:</SPAN>    
<SPAN CLASS="gutter">  16:</SPAN>    
<SPAN CLASS="gutter">  17:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  18:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter">  19:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  20:</SPAN>    
<SPAN CLASS="gutter">  21:</SPAN>    
<SPAN CLASS="gutter">  22:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  23:</SPAN>    <PRE><SPAN CLASS="gutter">   1:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyException <SPAN CLASS="syntax8">extends</SPAN> ChainableException <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   2:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   3:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter">   4:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">   5:</SPAN>    
<SPAN CLASS="gutter">   6:</SPAN>    
<SPAN CLASS="gutter">   7:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   8:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter">   9:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  10:</SPAN>    
<SPAN CLASS="gutter">  11:</SPAN>    
<SPAN CLASS="gutter">  12:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  13:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( cause );
<SPAN CLASS="gutter">  14:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  15:</SPAN>    
<SPAN CLASS="gutter">  16:</SPAN>    
<SPAN CLASS="gutter">  17:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  18:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter">  19:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  20:</SPAN>    
<SPAN CLASS="gutter">  21:</SPAN>    
<SPAN CLASS="gutter">  22:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  23:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter">  24:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  25:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  26:</SPAN>
</PRE>    <SPAN CLASS="syntax14">super</SPAN>( message, cause );
<SPAN CLASS="gutter">  24:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  25:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  26:</SPAN>
</PRE>
</P>

<P>
To make your own exception chainable, you simply need to follow the design
of the <tt>ChainableException</tt> class.  Below is a simple, non-javadoc
way to make your own:
<!--
import java.io.PrintStream;
import java.io.PrintWriter;
import net.sourceforge.groboutils.util.throwable.v1.IChainableException;
import net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper;

public class MyChainableException extends Exception
        implements IChainableException
{
    /** @serial */
    private ChainableExceptionHelper ceh;
    
    public MyChainableException() {
        super();
        this.ceh = new ChainableExceptionHelper( this );
    }
    
    public MyChainableException( String message ) {
        super( message );
        this.ceh = new ChainableExceptionHelper( this );
    }
    
    public MyChainableException( Throwable cause ) {
        super();
        this.ceh = new ChainableExceptionHelper( this, cause );
    }
    
    public MyChainableException( Throwable cause, String message ) {
        this( message, cause );
    }
    
    public MyChainableException( String message, Throwable cause ) {
        super( message );
        this.ceh = new ChainableExceptionHelper( this, cause );
    }
    
    public synchronized Throwable getCause() {
        return this.ceh.getCause();
    }
    
    public synchronized Throwable initCause( Throwable cause ) {
        return this.ceh.initCause( cause );
    }
    
    public void printStackTrace( PrintStream ps ) {
        this.ceh.printStackTrace( ps );
    }
    
    public void printStackTrace( PrintWriter pw ) {
        this.ceh.printStackTrace( pw );
    }
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter">   1:</SPAN><SPAN CLASS="syntax9">import</SPAN> java.io.PrintStream;
<SPAN CLASS="gutter">   2:</SPAN><SPAN CLASS="syntax9">import</SPAN> java.io.PrintWriter;
<SPAN CLASS="gutter">   3:</SPAN><SPAN CLASS="syntax9">import</SPAN> net.sourceforge.groboutils.util.throwable.v1.IChainableException;
<SPAN CLASS="gutter">   4:</SPAN><SPAN CLASS="syntax9">import</SPAN> net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper;
<SPAN CLASS="gutterH">   5:</SPAN>
<SPAN CLASS="gutter">   6:</SPAN><SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">class</SPAN> MyChainableException <SPAN CLASS="syntax8">extends</SPAN> Exception
<SPAN CLASS="gutter">   7:</SPAN>        <SPAN CLASS="syntax8">implements</SPAN> IChainableException
<SPAN CLASS="gutter">   8:</SPAN><SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">   9:</SPAN>    <SPAN CLASS="syntax3">/**</SPAN><SPAN CLASS="syntax3"> </SPAN><SPAN CLASS="syntax12">@serial</SPAN><SPAN CLASS="syntax3"> </SPAN><SPAN CLASS="syntax3">*/</SPAN>
<SPAN CLASS="gutterH">  10:</SPAN>    <SPAN CLASS="syntax8">private</SPAN> ChainableExceptionHelper ceh;
<SPAN CLASS="gutter">  11:</SPAN>    
<SPAN CLASS="gutter">  12:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  13:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter">  14:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN> );
<SPAN CLASS="gutterH">  15:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  16:</SPAN>    
<SPAN CLASS="gutter">  17:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  18:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter">  19:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN> );
<SPAN CLASS="gutterH">  20:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  21:</SPAN>    
<SPAN CLASS="gutter">  22:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  23:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>();
<SPAN CLASS="gutter">  24:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN>, cause );
<SPAN CLASS="gutterH">  25:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  26:</SPAN>    
<SPAN CLASS="gutter">  27:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( Throwable cause, String message ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  28:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>( message, cause );
<SPAN CLASS="gutter">  29:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  30:</SPAN>    
<SPAN CLASS="gutter">  31:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax6">MyChainableException</SPAN>( String message, Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  32:</SPAN>        <SPAN CLASS="syntax14">super</SPAN>( message );
<SPAN CLASS="gutter">  33:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ChainableExceptionHelper</SPAN>( <SPAN CLASS="syntax14">this</SPAN>, cause );
<SPAN CLASS="gutter">  34:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">  35:</SPAN>    
<SPAN CLASS="gutter">  36:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax8">synchronized</SPAN> Throwable <SPAN CLASS="syntax6">getCause</SPAN>() <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  37:</SPAN>        <SPAN CLASS="syntax8">return</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">getCause</SPAN>();
<SPAN CLASS="gutter">  38:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  39:</SPAN>    
<SPAN CLASS="gutterH">  40:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax8">synchronized</SPAN> Throwable <SPAN CLASS="syntax6">initCause</SPAN>( Throwable cause ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  41:</SPAN>        <SPAN CLASS="syntax8">return</SPAN> <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">initCause</SPAN>( cause );
<SPAN CLASS="gutter">  42:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  43:</SPAN>    
<SPAN CLASS="gutter">  44:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">void</SPAN> <SPAN CLASS="syntax6">printStackTrace</SPAN>( PrintStream ps ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutterH">  45:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">printStackTrace</SPAN>( ps );
<SPAN CLASS="gutter">  46:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  47:</SPAN>    
<SPAN CLASS="gutter">  48:</SPAN>    <SPAN CLASS="syntax8">public</SPAN> <SPAN CLASS="syntax10">void</SPAN> <SPAN CLASS="syntax6">printStackTrace</SPAN>( PrintWriter pw ) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">  49:</SPAN>        <SPAN CLASS="syntax14">this</SPAN>.ceh.<SPAN CLASS="syntax6">printStackTrace</SPAN>( pw );
<SPAN CLASS="gutterH">  50:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">  51:</SPAN><SPAN CLASS="syntax18">}</SPAN>
</PRE>
The claass implements IChainableException (to broadcast its JDK 1.4+
compatible chainable methods), and delegates method calls to the
<tt>ChainableExceptionHelper</tt> class.
</P>

<section name="tparse">Throwable Parsing</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
By using the
<tt>net.sourceforge.groboutils.util.throwable.v1.ThrowableParser</tt>
class, you can discover the details of the stack history of a
<tt>Throwable</tt> in any JDK.
</P>
<P>
For instance, if you need to know which method of a specific class
invoked the current method, you could perform:
<!--
String classToLookFor = c.getName(); 
Throwable t = new Throwable();
t.fillInStackTrace();
ThrowableParser tp = new ThrowableParser( t );
StackTraceLineParser stlp = tp.next();
String method = null;
int lineNumber = -1;
while (method == null && stlp != null) {
    if (classToLookFor.equals( stlp.getClassName() )) {
        method = stlp.getMethodName();
        lineNumber = stlp.getLineNumber();
    }
}

if (method != null) {
    System.out.println( "This method was called by class "+
        classToLookFor+" in method "+method+" on line "+
        lineNumber+"." );
} else {
    System.out.println( "Class "+classToLookFor+
        " didn't call this method." );
}
-->
<PRE CLASS="JavaCode"><SPAN CLASS="gutter"> 8:</SPAN>String classToLookFor <SPAN CLASS="syntax18">=</SPAN> c.<SPAN CLASS="syntax6">getName</SPAN>(); 
<SPAN CLASS="gutter"> 9:</SPAN>Throwable t <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">Throwable</SPAN>();
<SPAN CLASS="gutterH">10:</SPAN>t.<SPAN CLASS="syntax6">fillInStackTrace</SPAN>();
<SPAN CLASS="gutter">11:</SPAN>ThrowableParser tp <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax8">new</SPAN> <SPAN CLASS="syntax6">ThrowableParser</SPAN>( t );
<SPAN CLASS="gutter">12:</SPAN>StackTraceLineParser stlp <SPAN CLASS="syntax18">=</SPAN> tp.<SPAN CLASS="syntax6">next</SPAN>();
<SPAN CLASS="gutter">13:</SPAN>String method <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>;
<SPAN CLASS="gutter">14:</SPAN><SPAN CLASS="syntax10">int</SPAN> lineNumber <SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax18">-</SPAN><SPAN CLASS="syntax5">1</SPAN>;
<SPAN CLASS="gutterH">15:</SPAN><SPAN CLASS="syntax8">while</SPAN> (method <SPAN CLASS="syntax18">=</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN> <SPAN CLASS="syntax18">&amp;</SPAN><SPAN CLASS="syntax18">&amp;</SPAN> stlp <SPAN CLASS="syntax18">!</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">16:</SPAN>    <SPAN CLASS="syntax8">if</SPAN> (classToLookFor.<SPAN CLASS="syntax6">equals</SPAN>( stlp.<SPAN CLASS="syntax6">getClassName</SPAN>() )) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">17:</SPAN>        method <SPAN CLASS="syntax18">=</SPAN> stlp.<SPAN CLASS="syntax6">getMethodName</SPAN>();
<SPAN CLASS="gutter">18:</SPAN>        lineNumber <SPAN CLASS="syntax18">=</SPAN> stlp.<SPAN CLASS="syntax6">getLineNumber</SPAN>();
<SPAN CLASS="gutter">19:</SPAN>    <SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutterH">20:</SPAN><SPAN CLASS="syntax18">}</SPAN>
<SPAN CLASS="gutter">21:</SPAN>
<SPAN CLASS="gutter">22:</SPAN><SPAN CLASS="syntax8">if</SPAN> (method <SPAN CLASS="syntax18">!</SPAN><SPAN CLASS="syntax18">=</SPAN> <SPAN CLASS="syntax14">null</SPAN>) <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">23:</SPAN>    System.out.<SPAN CLASS="syntax6">println</SPAN>( <SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13">This</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">was</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">called</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">by</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">class</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutter">24:</SPAN>        classToLookFor<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">in</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax18">+</SPAN>method<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">on</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">line</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutterH">25:</SPAN>        lineNumber<SPAN CLASS="syntax18">+</SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13">.</SPAN><SPAN CLASS="syntax13">&quot;</SPAN> );
<SPAN CLASS="gutter">26:</SPAN><SPAN CLASS="syntax18">}</SPAN> <SPAN CLASS="syntax8">else</SPAN> <SPAN CLASS="syntax18">{</SPAN>
<SPAN CLASS="gutter">27:</SPAN>    System.out.<SPAN CLASS="syntax6">println</SPAN>( <SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13">Class</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax18">+</SPAN>classToLookFor<SPAN CLASS="syntax18">+</SPAN>
<SPAN CLASS="gutter">28:</SPAN>        <SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">didn't</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">call</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">this</SPAN><SPAN CLASS="syntax13"> </SPAN><SPAN CLASS="syntax13">method.</SPAN><SPAN CLASS="syntax13">&quot;</SPAN> );
<SPAN CLASS="gutter">29:</SPAN><SPAN CLASS="syntax18">}</SPAN>
</PRE>
</P>

<section name="clh">Class Load Helper</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The class
<tt>net.sourceforge.groboutils.util.classes.v1.ClassLoadHelper</tt>
aids the developer by providing convienent methods that can:
    <UL>
        <LI>
        return a class object without worrying about trapping the various
        exceptions;
        </LI>
        <LI>
        create a new object from the default constructor without trapping
        the various exceptions;
        </LI>
        <LI>
        create an object based on a property in a
        <tt>java.util.Hashtable</tt> that declares the class to instantiate;
        and
        </LI>
        <LI>
        easily load resources, including multiple resources of the same
        name.
        </LI>
    </UL>
The design wraps many JDK 1.2 and above calls into JDK 1.1-safe invocations. 
</P>


<section name="sstore">Singleton Stores</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The singleton pattern can be extremely powerful, conserving memory
requirements and hiding implementation details behind a factory-like
mechanism.
</P>
<P>
However, most implementations do not allow for robust access.  There exist
some needs to swap out one singleton for another.  Let's say, for example,
that an application has a utility class for loading class files from a URL
and dynamically loading them in the VM.  If this application was written
with JDK 1.1, it had to manually download the class files (possibly JAR
files), load them into a specialized class loader, then return the new
class.  However, when JDK 1.2 was released, those users could take advantage
of the URLClassLoader class.  The utility could be rewritten to use a
factory/proxy pattern, but that could break backwards compatibility.
Instead, the application could swap out the singleton with a JDK 1.1 or
JDK 1.2 implementation.
</P>
<P>
The GroboUtils Singleton Store class
(<tt>net.sourceforge.groboutils.util.classes.v1.SingletonStore</tt>)
allows for a class to contain a static reference to the Store, then allow
access to replace the Singleton in the store with another instance.
The SPISingletonStore does just this.
</P>

<section name="mstore">Multiple Stores</section>
<P><A HREF="#top"><I>Back to top</I></A></P>
<P>
The GroboUtils Multiple Store class
(<tt>net.sourceforge.groboutils.util.classes.v1.AbstractMultipleStore</tt>),
just like the <A HREF="#sstore">Singleton Stores</A>, allow for a central
location to manage the singleton, but the Multiple Store class allows for
several such instances to be stored, and new instances to be added as
needed.
</P>
</body>
</document>
