org.apache.camel.util
Class ResolverUtil<T>

java.lang.Object
  org.apache.camel.util.ResolverUtil<T>

Direct Known Subclasses:

WebSphereResolverUtil

public class ResolverUtil<T>
extends Object

ResolverUtil is used to locate classes that are available in the/a class path and meet arbitrary conditions. The two most common conditions are that a class implements/extends another class, or that is it annotated with a specific annotation. However, through the use of the ResolverUtil.Test class it is possible to search using arbitrary conditions.

A ClassLoader is used to locate all locations (directories and jar files) in the class path that contain classes within certain packages, and then to load those classes and check them. By default the ClassLoader returned by Thread.currentThread().getContextClassLoader() is used, but this can be overridden by calling setClassLoaders(Set) prior to invoking any of the find() methods.

General searches are initiated by calling the find(org.apache.camel.util.ResolverUtil.Test, String)} method and supplying a package name and a Test instance. This will cause the named package and all sub-packages to be scanned for classes that meet the test. There are also utility methods for the common use cases of scanning multiple packages for extensions of particular classes, or classes annotated with a specific annotation.

The standard usage pattern for the ResolverUtil class is as follows:

 resolverUtil<ActionBean> resolver = new ResolverUtil<ActionBean>();
 resolver.findImplementation(ActionBean.class, pkg1, pkg2);
 resolver.find(new CustomTest(), pkg1);
 resolver.find(new CustomTest(), pkg2);
 collection<ActionBean> beans = resolver.getClasses();
 

Nested Class Summary

static class	ResolverUtil.AnnotatedWith A Test that checks to see if each class is annotated with a specific annotation.
static class	ResolverUtil.IsA A Test that checks to see if each class is assignable to the provided class.
static interface	ResolverUtil.Test A simple interface that specifies how to test classes to determine if they are to be included in the results produced by the ResolverUtil.

Field Summary

protected org.apache.commons.logging.Log

log

Constructor Summary

ResolverUtil()

Method Summary

protected void	addIfMatching(ResolverUtil.Test test, String fqn) Add the class designated by the fully qualified class name provided to the set of resolved classes if and only if it is approved by the Test supplied.
void	find(ResolverUtil.Test test, String packageName) Scans for classes starting at the package provided and descending into subpackages.
protected void	find(ResolverUtil.Test test, String packageName, ClassLoader loader) Tries to find the reosurce in the package using the class loader.
void	findAnnotated(Class<? extends Annotation> annotation, String... packageNames) Attempts to discover classes that are annotated with to the annotation.
void	findImplementations(Class parent, String... packageNames) Attempts to discover classes that are assignable to the type provided.
Set<Class<? extends T>>	getClasses() Provides access to the classes discovered so far.
Set<ClassLoader>	getClassLoaders() Returns the classloaders that will be used for scanning for classes.
protected Enumeration<URL>	getResources(ClassLoader loader, String packageName) Strategy to get the resources by the given classloader.
void	setClassLoaders(Set<ClassLoader> classLoaders) Sets the ClassLoader instances that should be used when scanning for classes.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected final transient org.apache.commons.logging.Log log

Constructor Detail

ResolverUtil

public ResolverUtil()

Method Detail

getClasses

public Set<Class<? extends T>> getClasses()

Provides access to the classes discovered so far. If no calls have been made to any of the find() methods, this set will be empty.

Returns:

the set of classes that have been discovered.

getClassLoaders

public Set<ClassLoader> getClassLoaders()

Returns the classloaders that will be used for scanning for classes. If no explicit ClassLoader has been set by the calling, the context class loader will and the one that has loaded this class ResolverUtil be used.

Returns:

the ClassLoader instances that will be used to scan for classes

setClassLoaders

public void setClassLoaders(Set<ClassLoader> classLoaders)

Sets the ClassLoader instances that should be used when scanning for classes. If none is set then the context classloader will be used.

Parameters:

classLoaders - a ClassLoader to use when scanning for classes

findImplementations

public void findImplementations(Class parent,
                                String... packageNames)

Attempts to discover classes that are assignable to the type provided. In the case that an interface is provided this method will collect implementations. In the case of a non-interface class, subclasses will be collected. Accumulated classes can be accessed by calling getClasses().

Parameters:

parent - the class of interface to find subclasses or implementations of

packageNames - one or more package names to scan (including subpackages) for classes

findAnnotated

public void findAnnotated(Class<? extends Annotation> annotation,
                          String... packageNames)

Attempts to discover classes that are annotated with to the annotation. Accumulated classes can be accessed by calling getClasses().

Parameters:

annotation - the annotation that should be present on matching classes

packageNames - one or more package names to scan (including subpackages) for classes

find

public void find(ResolverUtil.Test test,
                 String packageName)

Scans for classes starting at the package provided and descending into subpackages. Each class is offered up to the Test as it is discovered, and if the Test returns true the class is retained. Accumulated classes can be fetched by calling getClasses().

Parameters:

test - an instance of ResolverUtil.Test that will be used to filter classes

packageName - the name of the package from which to start scanning for classes, e.g. net.sourceforge.stripes

find

protected void find(ResolverUtil.Test test,
                    String packageName,
                    ClassLoader loader)

Tries to find the reosurce in the package using the class loader.

Will handle both plain URL based classloaders and OSGi bundle loaders.

Parameters:

test - what to find

packageName - the package to search in

loader - the class loader

getResources

protected Enumeration<URL> getResources(ClassLoader loader,
                                        String packageName)
                                 throws IOException

Strategy to get the resources by the given classloader.

Notice that in WebSphere platforms there is a WebSphereResolverUtil to take care of WebSphere's odditiy of resource loading.

Parameters:

loader - the classloader

packageName - the packagename for the package to load

Returns:

URL's for the given package

Throws:

IOException - is thrown by the classloader

addIfMatching

protected void addIfMatching(ResolverUtil.Test test,
                             String fqn)

Add the class designated by the fully qualified class name provided to the set of resolved classes if and only if it is approved by the Test supplied.

Parameters:

test - the test used to determine if the class matches

fqn - the fully qualified name of a class