Using Util-Classes

Author:Matt Albrecht

Service Provider Interface Loading
Chainable Exceptions
Throwable Parsing
Class Load Helper
Singleton Stores
Multiple Stores

Service Provider Interface Loading

The SPILoader class knows how to parse a class loader for references to files under META-INF/services/classname. Multiple of these files may be defined per JAR file or directory in the classpath, so the SPILoader

The SPILoader class is used by the net.sourceforge.groboutils.autodoc.v1.AutoDoc class, so I'll review how that class uses the SPILoader to gain pluggable runtime loading of services.

AutoDoc does not directly reference the SPILoader, but rather uses the class SPISingletonStore to load and handle singleton instances. This SPISingletonStore, in turn, uses the SPILoader 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):

 97:    
 98:    
 99:    /**
100:     * Add a set of SPIs from the given class loader.
101:     */
102:    public void addSPI( ClassLoader cl )
103:            throws IOException
104:    {
105:        SPILoader spil = new SPILoader( this.baseClass, cl );
106:        
107:        while (spil.hasNext())
108:        {
109:            addSingleton( spil.nextProvier() );
110:        }
111:    }
112:}

Thus, the SPILoader can be used like an enumeration or iterator.

The SPILoader finds the files in the META-INF/services 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.

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.

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

Chainable Exceptions

Back to top

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:

   1:    try {
   2:        f = new FileWriter( myFile );
   3:    } catch (IOException ioe) {
   4:        throw new BuildException( ioe );
   5:    }

Note that the developer wraps the IOException inside the BuildException, recasting the exception to a different type. The BuildException class contains logic to store the embedded exception and display the embedded exception's stack trace on calls to BuildException.printStackTrace().

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

Extending the ChainableException class is much like extending an Exception:

   1:public class MyException extends ChainableException {
   2:    public MyException() {
   3:        super();
   4:    }
   5:    
   6:    
   7:    public MyException( String message ) {
   8:        super( message );
   9:    }
  10:    
  11:    
  12:    public MyException( Throwable cause ) {
  13:        super( cause );
  14:    }
  15:    
  16:    
  17:    public MyException( Throwable cause, String message ) {
  18:        super( message, cause );
  19:    }
  20:    
  21:    
  22:    public MyException( String message, Throwable cause ) {
  23:       1:public class MyException extends ChainableException {
   2:    public MyException() {
   3:        super();
   4:    }
   5:    
   6:    
   7:    public MyException( String message ) {
   8:        super( message );
   9:    }
  10:    
  11:    
  12:    public MyException( Throwable cause ) {
  13:        super( cause );
  14:    }
  15:    
  16:    
  17:    public MyException( Throwable cause, String message ) {
  18:        super( message, cause );
  19:    }
  20:    
  21:    
  22:    public MyException( String message, Throwable cause ) {
  23:        super( message, cause );
  24:    }
  25:}
  26:
    super( message, cause );
  24:    }
  25:}
  26:

To make your own exception chainable, you simply need to follow the design of the ChainableException class. Below is a simple, non-javadoc way to make your own:

   1:import java.io.PrintStream;
   2:import java.io.PrintWriter;
   3:import net.sourceforge.groboutils.util.throwable.v1.IChainableException;
   4:import net.sourceforge.groboutils.util.throwable.v1.ChainableExceptionHelper;
   5:
   6:public class MyChainableException extends Exception
   7:        implements IChainableException
   8:{
   9:    /** @serial */
  10:    private ChainableExceptionHelper ceh;
  11:    
  12:    public MyChainableException() {
  13:        super();
  14:        this.ceh = new ChainableExceptionHelper( this );
  15:    }
  16:    
  17:    public MyChainableException( String message ) {
  18:        super( message );
  19:        this.ceh = new ChainableExceptionHelper( this );
  20:    }
  21:    
  22:    public MyChainableException( Throwable cause ) {
  23:        super();
  24:        this.ceh = new ChainableExceptionHelper( this, cause );
  25:    }
  26:    
  27:    public MyChainableException( Throwable cause, String message ) {
  28:        this( message, cause );
  29:    }
  30:    
  31:    public MyChainableException( String message, Throwable cause ) {
  32:        super( message );
  33:        this.ceh = new ChainableExceptionHelper( this, cause );
  34:    }
  35:    
  36:    public synchronized Throwable getCause() {
  37:        return this.ceh.getCause();
  38:    }
  39:    
  40:    public synchronized Throwable initCause( Throwable cause ) {
  41:        return this.ceh.initCause( cause );
  42:    }
  43:    
  44:    public void printStackTrace( PrintStream ps ) {
  45:        this.ceh.printStackTrace( ps );
  46:    }
  47:    
  48:    public void printStackTrace( PrintWriter pw ) {
  49:        this.ceh.printStackTrace( pw );
  50:    }
  51:}

The claass implements IChainableException (to broadcast its JDK 1.4+ compatible chainable methods), and delegates method calls to the ChainableExceptionHelper class.

Throwable Parsing

Back to top

By using the net.sourceforge.groboutils.util.throwable.v1.ThrowableParser class, you can discover the details of the stack history of a Throwable in any JDK.

For instance, if you need to know which method of a specific class invoked the current method, you could perform:

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

Class Load Helper

Back to top

The class net.sourceforge.groboutils.util.classes.v1.ClassLoadHelper aids the developer by providing convienent methods that can:

return a class object without worrying about trapping the various exceptions;
create a new object from the default constructor without trapping the various exceptions;
create an object based on a property in a java.util.Hashtable that declares the class to instantiate; and
easily load resources, including multiple resources of the same name.

The design wraps many JDK 1.2 and above calls into JDK 1.1-safe invocations.

Singleton Stores

Back to top

The singleton pattern can be extremely powerful, conserving memory requirements and hiding implementation details behind a factory-like mechanism.

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.

The GroboUtils Singleton Store class (net.sourceforge.groboutils.util.classes.v1.SingletonStore) 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.

Multiple Stores

Back to top

The GroboUtils Multiple Store class (net.sourceforge.groboutils.util.classes.v1.AbstractMultipleStore), just like the Singleton Stores, 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.


This space graciously provided by the SourceForge project	Copyright © 2002-2004 GroboUtils Project. All rights reserved.

Using Util-Classes

Contents

Service Provider Interface Loading

Chainable Exceptions

Throwable Parsing

Class Load Helper

Singleton Stores

Multiple Stores