ptolemy.backtrack.eclipse.ast

Class LocalClassLoader

java.lang.Object

java.lang.ClassLoader

java.security.SecureClassLoader

java.net.URLClassLoader

ptolemy.backtrack.eclipse.ast.LocalClassLoader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class LocalClassLoader
extends java.net.URLClassLoader

A customized class loader that accepts class paths at run-time. It mimics the behavior of loading a class from the within of another class, as the following example:

    package pkg;
 class A {
 class B {
 class C {
 }
 }
 B.C field;
 }

The loading of class B.C requires some name resolving, which is done in the javac compiler, so that the type of field is always known as pkg.A$B$C at run-time.

Class name resolution implemented in this class also takes into account importations. In the following example, Hashtable is resolved as java.util.Hashtable:

    import java.util.*;
 class A {
 Hashtable table;
 }

This class loader only loads classes from the specified class paths and Java built-in classes. It does not use the CLASSPATH environment variable.

All the loaded classes are cached in a hash table so that they can be loaded efficiently the second time. This also means whenever two Class objects with the same name are returned, they also exist in the same memory location.

Since:

Ptolemy II 5.1

Version:

$Id$

Author:

Thomas Feng

Pt.AcceptedRating:

Red (tfeng)

Pt.ProposedRating:

Red (tfeng)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocalClassLoader.ClassImport The data structure that represent class importation.

Constructor Summary

Constructors

Constructor and Description
LocalClassLoader() Construct a class loader with no special class path.
LocalClassLoader(java.lang.String[] classPaths) Construct a class loader with a set of class paths specified as a string array.

Method Summary

Modifier and Type	Method and Description
void	addClassPath(java.lang.String path) Add a class path to the list of class paths to be searched from.
java.util.List<LocalClassLoader.ClassImport>	getImportedClasses() Get the list of names of imported classes.
java.util.List<java.lang.String>	getImportedPackages() Get the list of names of imported packages.
void	importClass(java.lang.String classFullName) Import a class.
void	importPackage(java.lang.String packageName) Import a package.
protected java.lang.Class<?>	loadClass(java.lang.String name, boolean resolve) Load a class with a given name.
java.lang.Class	searchForClass(java.lang.String name) Search for a class with its partial name in the current class or current package.
java.lang.Class	searchForClass(java.lang.StringBuffer name, java.lang.Class currentClass) Search for a class with a partial name in the given scope.
void	setCurrentClass(java.lang.Class c) Set the current class within which class names are to be solved with ClassLoader.loadClass(String).
void	setCurrentClass(java.lang.Class c, boolean resetPackage) Set the current class within which class names are to be solved with ClassLoader.loadClass(String).
void	setCurrentPackage(java.lang.String packageName) Set the current package.
void	setEnclosingClass(java.lang.String anonymousClass, java.lang.Class enclosingClass) Deprecated.

Methods inherited from class java.net.URLClassLoader

addURL, close, definePackage, findClass, findResource, findResources, getPermissions, getResourceAsStream, getURLs, newInstance, newInstance

Methods inherited from class java.security.SecureClassLoader

defineClass, defineClass

Methods inherited from class java.lang.ClassLoader

clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResource, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, registerAsParallelCapable, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalClassLoader

public LocalClassLoader()
                 throws java.net.MalformedURLException

Construct a class loader with no special class path. This class loader can only load Java built-in classes. More class paths may be added after this class loader is created.

Throws:

java.net.MalformedURLException - If a string is not a proper URL.

LocalClassLoader

public LocalClassLoader(java.lang.String[] classPaths)
                 throws java.net.MalformedURLException

Construct a class loader with a set of class paths specified as a string array. The class loader looks for classes in those paths in order.

Parameters:

classPaths - The array of class paths to be searched in order.

Throws:

java.net.MalformedURLException - If a string is not a proper URL.

Method Detail

addClassPath

public void addClassPath(java.lang.String path)

Add a class path to the list of class paths to be searched from.

Parameters:

path - The path to be added.

getImportedClasses

public java.util.List<LocalClassLoader.ClassImport> getImportedClasses()

Get the list of names of imported classes.

Returns:

The list.

getImportedPackages

public java.util.List<java.lang.String> getImportedPackages()

Get the list of names of imported packages.

Returns:

The list.

importClass

public void importClass(java.lang.String classFullName)

Import a class. This function mimics the import declaration used in a Java program. It adds a class to the import list to be considered at a later call to ClassLoader.loadClass(String).

Class importations "import packageName.className" takes precedence over package importations "import packageName.*".

Parameters:

classFullName - The full name of the class to be imported. It must contain the package name as its prefix. Nested classes are separated with ".", not "$", as used as name separator at run-time.

importPackage

public void importPackage(java.lang.String packageName)

Import a package. This function mimics the import declaration used in a Java program. It adds a package to the import list to be considered at a later call to searchForClass(String).

Class importations in the form of "import packageName.className" takes precedence over package importations in the form of "import packageName.*".

Parameters:

packageName - The full name of the package to be imported.

searchForClass

public java.lang.Class searchForClass(java.lang.String name)
                               throws java.lang.ClassNotFoundException

Search for a class with its partial name in the current class or current package.

Parameters:

name - The partial name of the class to be loaded.

Returns:

The class loaded with the given name in the scope.

Throws:

java.lang.ClassNotFoundException - If the class cannot be found.

See Also:

searchForClass(StringBuffer, Class)

searchForClass

public java.lang.Class searchForClass(java.lang.StringBuffer name,
                                      java.lang.Class currentClass)
                               throws java.lang.ClassNotFoundException

Search for a class with a partial name in the given scope. It is called in loadClass(String, boolean).

It takes the following steps in this name resolving:

1. Check if the name represents an array. An array type is treated as a special class in Java. The name of an array is either like "char[]" (source representation) or like "[C" (JVM internal representation). If this is the case, it recursively calls itself with the type of the elements in the array (if not primitive), and then loads the array class and return.
2. Check if the name corresponds to a nested class in the current class. In JVM representation, nested class names are separated with "$" from their containers. If so, the nested class is returned.
3. Check if the name is already a full class name, e.g., "java.lang.Class". If so, the class is loaded with ClassLoader.loadClass(String, boolean) and returned. Nested classes (case 2) take precedence over this full name resolution.
4. For every class explicitly imported with importClass(String), check if its simple class name (the last part) is the same as the first part of the class name to be searched for. If so, the imported class is loaded, and if necessary, its nested classes are searched.
5. Check if the partial name is relative to the current package.
6. Check if the partial name is relative to any package explicitly imported with importPackage(String). The implicitly imported package "java.lang" is also searched.

This function is considerably slower than ClassLoader.loadClass(String), which does not do a search but takes the given name for the full class name.

Parameters:

name - The partial name of the class to be loaded.

currentClass - The current class to be used as the scope. If it is null, current class is not considered.

Returns:

The class loaded with the given name in the scope.

Throws:

java.lang.ClassNotFoundException - If the class cannot be found.

See Also:

importClass(String), importPackage(String)

setCurrentClass

public void setCurrentClass(java.lang.Class c)

Set the current class within which class names are to be solved with ClassLoader.loadClass(String). This class can be an interface, a nested class, and an anonymous class (created at instantiation), as well as any normal class.

This function is the same as call setCurrentClass(c, true).

Parameters:

c - The class to be set as the current class. When it is null, both the current class and the current package are set undefined.

See Also:

setCurrentClass(Class, boolean)

setCurrentClass

public void setCurrentClass(java.lang.Class c,
                            boolean resetPackage)

Set the current class within which class names are to be solved with ClassLoader.loadClass(String). This class can be an interface, a nested class, and an anonymous class (created at instantiation), as well as any normal class.

If resetPackage is true, this function also sets the current package (see setCurrentPackage(String)) to the package which the class belongs to.

Parameters:

c - The class to be set as the current class. When it is null, both the current class and the current package are set undefined.

resetPackage - If true, the current package is set to be the package that contains class c; when c is null, the current package is also set to null. If false, do not modify the current package.

setCurrentPackage

public void setCurrentPackage(java.lang.String packageName)

Set the current package. The current package is the package that the current class belongs to. ClassLoader.loadClass(String) searches for classes in the current package.

Parameters:

packageName - The package name to be set as the current package. When it is null, the current package is set undefined.

setEnclosingClass

public void setEnclosingClass(java.lang.String anonymousClass,
                              java.lang.Class enclosingClass)

Deprecated.

Set the enclosing class of an anonymous class (a class without a name that subclasses another one at instantiation time). In Java 1.4, enclosing class information cannot obtained from the anonymous class object. This problem is solved by extending the functionality of the Class class in Java 1.5.

While TypeAnalyzer analyzes an AST, it registers the enclosing class of each anonymous class that it sees. This helps the class loader to resolve enclosing classes.

The same problem is solved in TypeAnalyzer by using a stack to record all the classes entered so far.

Parameters:

anonymousClass - The internal name of an anonymous class (using a number to identify it), which is used at run-time by the Java virtual machine.

enclosingClass - The Class object representing the enclosing class.

loadClass

protected java.lang.Class<?> loadClass(java.lang.String name,
                                       boolean resolve)
                                throws java.lang.ClassNotFoundException

Load a class with a given name. It is called in ClassLoader.loadClass(String name), the function that users use to dynamically resolve classes.

For efficiency, the class name must be complete. If resolve is true, it uses ClassLoader.resolveClass(Class) to further resolve the class. Resolving a class is a step in preparing the class for use. It is not always required. When Java virtual machine merely uses the signature of the loaded class to perform dynamic verification, ClassLoader.loadClass(String) calls this function with resolve equal to false when this is the case.

Overrides:

loadClass in class java.lang.ClassLoader

Parameters:

name - The partial name of the class to be loaded.

resolve - Whether ClassLoader.resolveClass(Class) should be called.

Returns:

The class loaded with the given name in the scope.

Throws:

java.lang.ClassNotFoundException - If the class cannot be found.