net.sourceforge.groboutils.util.classes.v1
Class ClassLoadHelper

java.lang.Object
  net.sourceforge.groboutils.util.classes.v1.ClassLoadHelper

public class ClassLoadHelper

extends java.lang.Object

Utility class for loading classes and creating instances. Much of the basic operation have been ripped from net.groboutils.util.classes.v1.ClassUtil in the GroboUtils package. If the helper's class loader is null, then it will use the Thread's context ClassLoader.

Note that resource loading is very tricky. Finding the right classloader and right methods to invoke is JDK dependent.

Since:

March 16, 2002

Version:

$Date: 2003/02/10 22:52:36 $

Author:

Matt Albrecht groboclown@users.sourceforge.net

Constructor Summary

ClassLoadHelper()
Default constructor - will use the Thread's context class loader for each class discovery.

ClassLoadHelper(java.lang.Class clazz)
Use the given class's classloader.

ClassLoadHelper(java.lang.ClassLoader cl)
Loads the helper with the given class loader.

Method Summary

java.lang.Object	createObject(java.lang.Class c) Creates an Object from the given Class, using its default constructor.
java.lang.Object	createObject(java.lang.Class c, boolean swallowExceptions) Creates an Object from the given Class, using its default constructor.
java.lang.Object	createObject(java.lang.String className) Creates a new instance of the class with the given className using the default constructor.
java.lang.Object	createObject(java.lang.String className, boolean swallowExceptions) Creates a new instance of the class with the given className using the default constructor.
java.lang.Object	createObjectFromProperty(java.lang.String propertyClassName, java.lang.Class defaultClass, boolean swallowExceptions) Loads an object using the createObject( String, boolean ) method above, using the given System property's value as the class name.
java.lang.Object	createObjectFromProperty(java.lang.String propertyClassName, java.lang.Class defaultClass, java.util.Hashtable properties, boolean swallowExceptions) Loads an object using the createObject( String, boolean ) method above, using the given Hashtable's property's value as the class name.
protected static java.lang.reflect.Method	discoverContextClassloaderMethod()
protected static java.lang.reflect.Method	discoverGetResourcesMethod()
protected static java.lang.reflect.Method	discoverGetSystemResourcesMethod()
protected java.lang.String	getAbsoluteResourceName(java.lang.String name)
java.lang.Class	getClass(java.lang.String name) Loads the requested class from the helper's classloader, and returns the Class instance, or null if the class could not be found.
java.lang.Class	getClass(java.lang.String name, boolean swallowExceptions) Loads the requested class from the helper's classloader, and returns the Class instance, or null if the class could not be found.
protected java.lang.ClassLoader	getClassLoader() Gets the correct class loader.
java.net.URL	getResource(java.lang.String name) Loads a resource with the given name, using the correct ClassLoader.
java.net.URL	getResource(java.lang.String name, java.lang.ClassLoader cl) Loads a resource with the given name, using the given ClassLoader.
java.io.InputStream	getResourceAsStream(java.lang.String name) Loads a resource with the given name, using the correct ClassLoader.
java.util.Enumeration	getResources(java.lang.String name) Loads a resource with the given name, using the correct ClassLoader.
java.util.Enumeration	getResources(java.lang.String name, java.lang.ClassLoader cl) Loads a resource with the given name, using the correct ClassLoader.
java.net.URL	getSystemResource(java.lang.String name) Loads a resource with the given name, using the correct ClassLoader.
java.util.Enumeration	getSystemResources(java.lang.String name) Get the resource associated with the given name from the System classloader.
protected static java.lang.ClassLoader	getThreadClassLoader(java.lang.Thread t) Use reflection to get the thread (context) class loader.
protected java.lang.Class	loadClass(java.lang.String name) Loads a class with the given name, using the correct ClassLoader.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClassLoadHelper

public ClassLoadHelper()

Default constructor - will use the Thread's context class loader for each class discovery.

ClassLoadHelper

public ClassLoadHelper(java.lang.Class clazz)

Use the given class's classloader.

Parameters:

clazz - the class to pull the classloader from.

Throws:

java.lang.NullPointerException - if clazz is null.

ClassLoadHelper

public ClassLoadHelper(java.lang.ClassLoader cl)

Loads the helper with the given class loader. If the given class loader is null, then it will use the Thread's context class loader.

Parameters:

cl - the classloader to pull all requested classes from, or it will use the thread's context class loader if cl is null.

See Also:

Thread.getContextClassLoader()

Method Detail

getClass

public java.lang.Class getClass(java.lang.String name)

Loads the requested class from the helper's classloader, and returns the Class instance, or null if the class could not be found.

Parameters:

name - the name of the class to load.

Returns:

the discovered Class, or null if it could not be found.

getClass

public java.lang.Class getClass(java.lang.String name,
                                boolean swallowExceptions)

Loads the requested class from the helper's classloader, and returns the Class instance, or null if the class could not be found.

Parameters:

name - the name of the class to load.

swallowExceptions - true if this method is to return

Returns:

the discovered Class, or null if it could not be found and swallowExceptions is true.

Throws:

java.lang.IllegalStateException - if there was an error during initialization and swallowExceptions is false.

createObject

public java.lang.Object createObject(java.lang.String className)

Creates a new instance of the class with the given className using the default constructor. If there was an error during the creation, such as the class was not found, the class does not have a default constructor, or the constructor threw an exception, then null is returned.

Parameters:

className - the name of the class to create an instance.

Returns:

the new instance, or null if there was a problem.

See Also:

getClass( String ), createObject( String, boolean ), createObject( Class ), createObject( Class, boolean )

createObject

public java.lang.Object createObject(java.lang.String className,
                                     boolean swallowExceptions)

Creates a new instance of the class with the given className using the default constructor. If there was an error during the creation, such as the class was not found, the class does not have a default constructor, or the constructor threw an exception, then an IllegalStateException will be thrown only if swallowExceptions is false; otherwise, null will be returned.

Parameters:

className - the name of the class to create an instance.

swallowExceptions - true if this method is to return null on any exceptions, or false if it should throw an IllegalStateException on any error.

Returns:

the new instance.

Throws:

java.lang.IllegalStateException - if there was an error during initialization and swallowExceptions is false.

See Also:

getClass( String ), createObject( String ), createObject( Class ), createObject( Class, boolean )

createObject

public java.lang.Object createObject(java.lang.Class c)

Creates an Object from the given Class, using its default constructor. All creation exceptions are swallowed. If the object could not be created, then null is returned.

Parameters:

c - the Class object from which a new instance will be created using its default constructor.

Returns:

the instantiated object, or null if c is null, or if there was an error during initialization.

createObject

public java.lang.Object createObject(java.lang.Class c,
                                     boolean swallowExceptions)

Creates an Object from the given Class, using its default constructor. If there was an error during the creation, such as the class was not found, the class does not have a default constructor, or the constructor threw an exception, then an IllegalStateException will be thrown only if swallowExceptions is false; otherwise, null will be returned.

Parameters:

c - the Class object from which a new instance will be created using its default constructor.

swallowExceptions - true if this method is to return null on any exceptions, or false if it should throw an IllegalStateException on any error.

Returns:

the instantiated object, or null if c is null, or if there was an error during initialization and swallowExceptions is true.

Throws:

java.lang.IllegalStateException - if there was an error during initialization and swallowExceptions is false.

createObjectFromProperty

public java.lang.Object createObjectFromProperty(java.lang.String propertyClassName,
                                                 java.lang.Class defaultClass,
                                                 boolean swallowExceptions)

Loads an object using the createObject( String, boolean ) method above, using the given System property's value as the class name. If the System property is not defined, then it resorts to the default class.

Parameters:

propertyClassName - the System Property name, whose value will be used as a fully-qualified Class name to load and instantiate and return.

defaultClass - if the System Property propertyClassName is not defined, then this will be the class to instantiate and return.

swallowExceptions - true if this method is to return null on any exceptions, or false if it should throw an IllegalStateException on any error.

Returns:

the instantiated class.

Throws:

java.lang.IllegalStateException - if there was an error during initialization and swallowExceptions is false.

createObjectFromProperty

public java.lang.Object createObjectFromProperty(java.lang.String propertyClassName,
                                                 java.lang.Class defaultClass,
                                                 java.util.Hashtable properties,
                                                 boolean swallowExceptions)

Loads an object using the createObject( String, boolean ) method above, using the given Hashtable's property's value as the class name. If the Hashtable property is not defined, then it resorts to the default class. If the Hashtable is null, then the System property will be used instead.

Parameters:

propertyClassName - the System Property name, whose value will be used as a fully-qualified Class name to load and instantiate and return.

defaultClass - if the System Property propertyClassName is not defined, then this will be the class to instantiate and return.

properties - a Hashtable of String -> String mappings.

swallowExceptions - true if this method is to return null on any exceptions, or false if it should throw an IllegalStateException on any error.

Returns:

the instantiated class.

Throws:

java.lang.IllegalStateException - if there was an error during initialization and swallowExceptions is false.

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String name)
                                        throws java.io.IOException

Loads a resource with the given name, using the correct ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

Returns:

the resource as an InputStream, which may possibly be null.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResourceAsStream( String )

getResource

public java.net.URL getResource(java.lang.String name)
                         throws java.io.IOException

Loads a resource with the given name, using the correct ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

Returns:

the resource name as an URL, which may possibly be null.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResourceAsStream( String )

getResource

public java.net.URL getResource(java.lang.String name,
                                java.lang.ClassLoader cl)
                         throws java.io.IOException

Loads a resource with the given name, using the given ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

cl - the classloader to load the reference from.

Returns:

the resource name as an URL, which may possibly be null.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResourceAsStream( String )

getSystemResource

public java.net.URL getSystemResource(java.lang.String name)
                               throws java.io.IOException

Loads a resource with the given name, using the correct ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

Returns:

the resource name as an URL, which may possibly be null.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResourceAsStream( String )

getResources

public java.util.Enumeration getResources(java.lang.String name)
                                   throws java.io.IOException

Loads a resource with the given name, using the correct ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

Returns:

the list of resource URLs, which may NOT be null (implementation ensures it is not null).

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResources( String ), ClassLoader.getResourceAsStream( String )

getResources

public java.util.Enumeration getResources(java.lang.String name,
                                          java.lang.ClassLoader cl)
                                   throws java.io.IOException

Loads a resource with the given name, using the correct ClassLoader. Does not swallow exceptions. See the JDK documentation on resources (they are pretty much files that are in the classpath of the classloader). Yes, this can be used successfully to get a class file (well, JDK 1.1 throws a SecurityException if this is attempted).

Parameters:

name - absolute referece to the expected resource.

cl - the classloader to load the references from.

Returns:

a non-null list of resource URLs for the resource name.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResources( String ), ClassLoader.getResourceAsStream( String )

getSystemResources

public java.util.Enumeration getSystemResources(java.lang.String name)
                                         throws java.io.IOException

Get the resource associated with the given name from the System classloader. This will never return null.

Parameters:

name - absolute referece to the expected resource.

Returns:

a non-null list of URLs matching the resource.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

ClassLoader.getResource( String ), ClassLoader.getResources( String ), ClassLoader.getResourceAsStream( String )

getClassLoader

protected java.lang.ClassLoader getClassLoader()

Gets the correct class loader. May return null.

Returns:

the ClassLoader

loadClass

protected java.lang.Class loadClass(java.lang.String name)
                             throws java.lang.ClassNotFoundException,
                                    java.lang.LinkageError,
                                    java.lang.IllegalArgumentException

Loads a class with the given name, using the correct ClassLoader. Does not swallow exceptions.

Throws:

java.lang.ClassNotFoundException - if the class name is not known by the class loader.

java.lang.LinkageError - if there was a basic class loader error.

java.lang.IllegalArgumentException - if the class doesn't smell right to JDK 1.1.

getThreadClassLoader

protected static java.lang.ClassLoader getThreadClassLoader(java.lang.Thread t)

Use reflection to get the thread (context) class loader.

discoverContextClassloaderMethod

protected static java.lang.reflect.Method discoverContextClassloaderMethod()

discoverGetResourcesMethod

protected static java.lang.reflect.Method discoverGetResourcesMethod()

discoverGetSystemResourcesMethod

protected static java.lang.reflect.Method discoverGetSystemResourcesMethod()

getAbsoluteResourceName

protected java.lang.String getAbsoluteResourceName(java.lang.String name)