umontreal.iro.lecuyer.util
Class ClassFinder

java.lang.Object
  umontreal.iro.lecuyer.util.ClassFinder

All Implemented Interfaces:

Serializable, Cloneable

public class ClassFinder
extends Object
implements Cloneable, Serializable

Utility class used to convert a simple class name to a fully qualified class object. The Class class can be used to obtain information about a class (its name, its fields, methods, constructors, etc.), and to construct objects, even if the exact class is known at runtime only. It provides a forName static method converting a string to a Class, but the given string must be a fully qualified name.

Sometimes, configuration files may need to contain Java class names. After they are extracted from the file, these class names are given to forName to be converted into Class objects. Unfortunately, only fully qualified class names will be accepted as input, which clutters configuration files, especially if long package names are used. This class permits the definition of a set of import declarations in a way similar to the Java Language Specification. It provides methods to convert a simple class name to a Class object and to generate a simple name from a Class object, based on the import rules.

The first step for using a class finder is to construct an instance of this class. Then, one needs to retrieve the initially empty list of import declarations by using getImports, and update it with the actual import declarations. Then, the method findClass can find a class using the import declarations. For example, the following code retrieves the class object for the List class in package java.util

ClassFinder cf = new ClassFinder();
cf.getImports().add ("java.util.*");
Class<?> listClass = cf.findClass ("List");

See Also:

Serialized Form

Constructor Summary

ClassFinder()
Constructs a new class finder with an empty list of import declarations.

Method Summary

ClassFinder	clone() Clones this class finder, and copies its lists of import declarations.
Class<?>	findClass(String name) Tries to find the class corresponding to the simple name name.
List<String>	getImports() Returns the current list of import declarations.
String	getSimpleName(Class<?> cls) Returns the simple name of the class cls that can be used when the imports contained in this class finder are used.
void	restoreImports() Restores the list of import declarations.
void	saveImports() Saves the current import list on the import stack.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClassFinder

public ClassFinder()

Constructs a new class finder with an empty list of import declarations.

Method Detail

getImports

public List<String> getImports()

Returns the current list of import declarations. This list may contain only String's of the form java.class.name or java.package.name.*.

Returns:

the current list of import declarations.

saveImports

public void saveImports()

Saves the current import list on the import stack. This method makes a copy of the list returned by getImports and puts it on top of a stack to be restored later by restoreImports.

restoreImports

public void restoreImports()

Restores the list of import declarations. This method removes the last list of import declarations from the stack. If the stack contains only one list, this list is cleared.

findClass

public Class<?> findClass(String name)
                   throws ClassNotFoundException,
                          NameConflictException

Tries to find the class corresponding to the simple name name. The method first considers the argument as a fully qualified class name and calls forName (name). If the class cannot be found, it considers the argument as a simple name. A simple name refers to a class without specifying the package declaring it. To convert simple names to qualified names, the method iterates through all the strings in the list returned by getImports, applying the same rules as a Java compiler to resolve the class name. However, if an imported package or class does not exist, it will be ignored whereas the compiler would stop with an error.

For the class with simple name name to be loaded, it must be imported explicitly (single-type import) or one of the imported packages must contain it (type import on-demand). If the class with name name is imported explicitly, this import declaration has precedence over any imported packages. If several import declaration match the given simple name, e.g., if several fully qualified names with the same simple name are imported, or if a class with simple name name exists in several packages, a NameConflictException is thrown.

Parameters:

name - the simple name of the class.

Returns:

a reference to the class being loaded.

Throws:

ClassNotFoundException - if the class cannot be loaded.

NameConflictException - if a name conflict occurred.

getSimpleName

public String getSimpleName(Class<?> cls)

Returns the simple name of the class cls that can be used when the imports contained in this class finder are used. For example, if java.lang.String.class is given to this method, String is returned if java.lang.* is among the import declarations.

Note: this method does not try to find name conflicts. This operation is performed by findClass only. For example, if the list of imported declarations contains foo.bar.* and test.Foo, and the simple name for test.Foo is queried, the method returns Foo even if the package foo.bar contains a Foo class.

Parameters:

cls - the class for which the simple name is queried.

Returns:

the simple class name.

clone

public ClassFinder clone()

Clones this class finder, and copies its lists of import declarations.

Overrides:

clone in class Object