org.clapper.util.classutil

Class ClassFinder

java.lang.Object

org.clapper.util.classutil.ClassFinder

public class ClassFinder
extends java.lang.Object

A ClassFinder object is used to find classes. By default, an instantiated ClassFinder won't find any classes; you have to add the classpath (via a call to addClassPath()), add jar files, add zip files, and/or add directories to the ClassFinder so it knows where to look. Adding a jar file to a ClassFinder causes the ClassFinder to look at the jar's manifest for a "Class-Path" entry; if the ClassFinder finds such an entry, it adds the contents to the search path, as well. After the ClassFinder has been "primed" with things to search, you call its findClasses() method to have it search for the classes, optionally passing a ClassFilter that can be used to filter out classes you're not interested in.

This package also contains a rich set of ClassFilter implementations, including:

• A RegexClassFilter for filtering class names on a regular expression
• Filters for testing various class attributes (such as whether a class is an interface, or a subclass of a known class, etc.
• Filters that can combine other filters in logical operations

The following example illustrates how you might use a ClassFinder to locate all non-abstract classes that implement the ClassFilter interface, searching the classpath as well as anything specified on the command line.

 import org.clapper.util.classutil.*;

 public class Test
 {
     public static void main (String[] args) throws Throwable
     {
         ClassFinder finder = new ClassFinder();
         for (String arg : args)
             finder.add(new File(arg));

         ClassFilter filter =
             new AndClassFilter
                 // Must not be an interface
                 (new NotClassFilter (new InterfaceOnlyClassFilter()),

                 // Must implement the ClassFilter interface
                 new SubclassClassFilter (ClassFilter.class),

                 // Must not be abstract
                 new NotClassFilter (new AbstractClassFilter()));

         Collection<ClassInfo> foundClasses = new ArrayList<ClassInfo>();
         finder.findClasses (foundClasses, filter);

         for (ClassInfo classInfo : foundClasses)
             System.out.println ("Found " + classInfo.getClassName());
     }
 }
 

This class, and the ClassInfo class, rely on the ASM byte-code manipulation library. If that library is not available, this package will not work. See asm.objectweb.org for details on ASM.

WARNING: This class is not thread-safe.

Constructor Summary

Constructors

Constructor and Description
ClassFinder() Create a new ClassFinder that will search for classes using the default class loader.

Method Summary

Modifier and Type	Method and Description
int	add(java.util.Collection<java.io.File> files) Add a Collection of jar files, zip files and/or directories to the list of places to search for classes.
boolean	add(java.io.File file) Add a jar file, zip file or directory to the list of places to search for classes.
int	add(java.io.File[] files) Add an array jar files, zip files and/or directories to the list of places to search for classes.
void	addClassPath() Add the contents of the system classpath for classes.
void	clear() Clear the finder's notion of where to search.
int	findAllInterfaces(ClassInfo classInfo, java.util.Map<java.lang.String,ClassInfo> interfaces) Intended to be called only from a ClassFilter object's accept() method, this method attempts to find all the interfaces implemented by given class (directly and indirectly), by checking all the currently-loaded class data.
int	findAllSuperClasses(ClassInfo classInfo, java.util.Map<java.lang.String,ClassInfo> superClasses) Intended to be called only from a ClassFilter object's accept() method, this method attempts to find all the superclasses (except java.lang.Objectfor a given class, by checking all the currently-loaded class data.
int	findClasses(java.util.Collection<ClassInfo> classes) Find all classes in the search areas, implicitly accepting all of them.
int	findClasses(java.util.Collection<ClassInfo> classes, ClassFilter filter) Search all classes in the search areas, keeping only those that pass the specified filter.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClassFinder

public ClassFinder()

Create a new ClassFinder that will search for classes using the default class loader.

Method Detail

addClassPath

public void addClassPath()

Add the contents of the system classpath for classes.

add

public boolean add(java.io.File file)

Add a jar file, zip file or directory to the list of places to search for classes.

Parameters:

file - the jar file, zip file or directory

Returns:

true if the file was suitable for adding; false if it was not a jar file, zip file, or directory.

add

public int add(java.io.File[] files)

Add an array jar files, zip files and/or directories to the list of places to search for classes.

Parameters:

files - the array of jar files, zip files and/or directories. The array can contain a mixture of all of the above.

Returns:

the total number of items from the array that were actually added. (Elements that aren't jars, zip files or directories are skipped.)

add

public int add(java.util.Collection<java.io.File> files)

Add a Collection of jar files, zip files and/or directories to the list of places to search for classes.

Parameters:

files - the collection of jar files, zip files and/or directories.

Returns:

the total number of items from the collection that were actually added. (Elements that aren't jars, zip files or directories are skipped.)

clear

public void clear()

Clear the finder's notion of where to search.

findClasses

public int findClasses(java.util.Collection<ClassInfo> classes)

Find all classes in the search areas, implicitly accepting all of them.

Parameters:

classes - where to store the resulting matches

Returns:

the number of matched classes added to the collection

findClasses

public int findClasses(java.util.Collection<ClassInfo> classes,
                       ClassFilter filter)

Search all classes in the search areas, keeping only those that pass the specified filter.

Parameters:

classes - where to store the resulting matches

filter - the filter, or null for no filter

Returns:

the number of matched classes added to the collection

findAllSuperClasses

public int findAllSuperClasses(ClassInfo classInfo,
                               java.util.Map<java.lang.String,ClassInfo> superClasses)

Intended to be called only from a ClassFilter object's accept() method, this method attempts to find all the superclasses (except java.lang.Objectfor a given class, by checking all the currently-loaded class data.

Parameters:

classInfo - the ClassInfo objects for the class

superClasses - where to store the ClassInfo objects for the superclasses. The map is indexed by class name.

Returns:

the number of superclasses found

findAllInterfaces

public int findAllInterfaces(ClassInfo classInfo,
                             java.util.Map<java.lang.String,ClassInfo> interfaces)

Intended to be called only from a ClassFilter object's accept() method, this method attempts to find all the interfaces implemented by given class (directly and indirectly), by checking all the currently-loaded class data.

Parameters:

classInfo - the ClassInfo objects for the class

interfaces - where to store the ClassInfo objects for the interfaces. The map is indexed by class name

Returns:

the number of interfaces found