javassist
Class ClassPool

java.lang.Object
  extended byjavassist.ClassPool

public class ClassPool
extends java.lang.Object

A container of CtClass objects. A CtClass object must be obtained from this object. If get() is called on this object, it searches various sources represented by ClassPath to find a class file and then it creates a CtClass object representing that class file. The created object is returned to the caller.

Memory consumption memo:

ClassPool objects hold all the CtClasses that have been created so that the consistency among modified classes can be guaranteed. Thus if a large number of CtClasses are processed, the ClassPool will consume a huge amount of memory. To avoid this, a ClassPool object should be recreated, for example, every hundred classes processed. Note that getDefault() is a singleton factory. Otherwise, detach() in CtClass should be used to avoid huge memory consumption.

ClassPool hierarchy:

ClassPools can make a parent-child hierarchy as java.lang.ClassLoaders. If a ClassPool has a parent pool, get() first asks the parent pool to find a class file. Only if the parent could not find the class file, get() searches the ClassPaths of the child ClassPool. This search order is reversed if ClassPath.childFirstLookup is true.

See Also:
CtClass, ClassPath

Field Summary
 boolean childFirstLookup
          Determines the search order.
 
Constructor Summary
ClassPool()
          Creates a root class pool.
ClassPool(ClassPool parent)
          Creates a class pool.
 
Method Summary
 ClassPath appendClassPath(ClassPath cp)
          Appends a ClassPath object to the end of the search path.
 ClassPath appendClassPath(java.lang.String pathname)
          Appends a directory or a jar (or zip) file to the end of the search path.
 void appendPathList(java.lang.String pathlist)
          Appends directories and jar files for search.
 ClassPath appendSystemPath()
          Appends the system search path to the end of the search path.
 java.net.URL find(java.lang.String classname)
          Searches the class path to obtain the URL of the class file specified by classname.
 CtClass get(java.lang.String classname)
          Reads a class file from the source and returns a reference to the CtClass object representing that class file.
 CtClass[] get(java.lang.String[] classnames)
          Reads class files from the source and returns an array of CtClass objects representing those class files.
 CtClass getAndRename(java.lang.String orgName, java.lang.String newName)
          Reads a class file and constructs a CtClass object with a new name.
static ClassPool getDefault()
          Returns the default class pool.
 CtMethod getMethod(java.lang.String classname, java.lang.String methodname)
          Reads a class file and obtains a compile-time method.
 ClassPath insertClassPath(ClassPath cp)
          Insert a ClassPath object at the head of the search path.
 ClassPath insertClassPath(java.lang.String pathname)
          Inserts a directory or a jar (or zip) file at the head of the search path.
 java.lang.Object[] lookupCflow(java.lang.String name)
          Undocumented method.
 CtClass makeClass(java.io.InputStream classfile)
          Creates a new class (or interface) from the given class file.
 CtClass makeClass(java.lang.String classname)
          Creates a new public class.
 CtClass makeClass(java.lang.String classname, CtClass superclass)
          Creates a new public class.
 CtClass makeInterface(java.lang.String name)
          Creates a new public interface.
 CtClass makeInterface(java.lang.String name, CtClass superclass)
          Creates a new public interface.
 void recordInvalidClassName(java.lang.String name)
          Records a name that never exists.
 void removeClassPath(ClassPath cp)
          Detatches the ClassPath object from the search path.
 java.lang.Class toClass(CtClass clazz)
          Converts the given class to a java.lang.Class object.
 java.lang.Class toClass(CtClass ct, java.lang.ClassLoader loader)
          Converts the class to a java.lang.Class object.
 java.lang.String toString()
          Returns the class search path.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

childFirstLookup

public boolean childFirstLookup
Determines the search order.

If this field is true, get() first searches the class path associated to this ClassPool and then the class path associated with the parent ClassPool. Otherwise, the class path associated with the parent is searched first.

The default value is false.

Constructor Detail

ClassPool

public ClassPool()
Creates a root class pool. No parent class pool is specified.


ClassPool

public ClassPool(ClassPool parent)
Creates a class pool.

Parameters:
parent - the parent of this class pool. If this is a root class pool, this parameter must be null.
See Also:
getDefault()
Method Detail

getDefault

public static ClassPool getDefault()
Returns the default class pool. The returned object is always identical since this method is a singleton factory.

The default class pool searches the system search path, which usually includes the platform library, extension libraries, and the search path specified by the -classpath option or the CLASSPATH environment variable.

When this method is called for the first time, the default class pool is created with the following code snippet:

If the default class pool cannot find any class files, try ClassClassPath and LoaderClassPath.

See Also:
ClassClassPath, LoaderClassPath

toString

public java.lang.String toString()
Returns the class search path.


recordInvalidClassName

public void recordInvalidClassName(java.lang.String name)
Records a name that never exists. For example, a package name can be recorded by this method. This would improve execution performance since get() does not search the class path at all if the given name is an invalid name recorded by this method. Note that searching the class path takes relatively long time.

Parameters:
name - a class name (separeted by dot).

lookupCflow

public java.lang.Object[] lookupCflow(java.lang.String name)
Undocumented method. Do not use; internal-use only.

Parameters:
name - the name of $cflow variable

getAndRename

public CtClass getAndRename(java.lang.String orgName,
                            java.lang.String newName)
                     throws NotFoundException
Reads a class file and constructs a CtClass object with a new name. This method is useful if you want to generate a new class as a copy of another class (except the class name). For example, returns a CtClass object representing Pair class. The definition of Pair is the same as that of Point class except the class name since Pair is defined by reading Point.class.

Parameters:
orgName - the original (fully-qualified) class name
newName - the new class name
Throws:
NotFoundException

get

public CtClass get(java.lang.String classname)
            throws NotFoundException
Reads a class file from the source and returns a reference to the CtClass object representing that class file. If that class file has been already read, this method returns a reference to the CtClass created when that class file was read at the first time.

If classname ends with "[]", then this method returns a CtClass object for that array type.

To obtain an inner class, use "$" instead of "." for separating the enclosing class name and the inner class name.

Parameters:
classname - a fully-qualified class name.
Throws:
NotFoundException

find

public java.net.URL find(java.lang.String classname)
Searches the class path to obtain the URL of the class file specified by classname. It is also used to determine whether the class file exists.

Parameters:
classname - a fully-qualified class name.
Returns:
null if the class file could not be found.
See Also:
CtClass.getURL()

get

public CtClass[] get(java.lang.String[] classnames)
              throws NotFoundException
Reads class files from the source and returns an array of CtClass objects representing those class files.

If an element of classnames ends with "[]", then this method returns a CtClass object for that array type.

Parameters:
classnames - an array of fully-qualified class name.
Throws:
NotFoundException

getMethod

public CtMethod getMethod(java.lang.String classname,
                          java.lang.String methodname)
                   throws NotFoundException
Reads a class file and obtains a compile-time method.

Parameters:
classname - the class name
methodname - the method name
Throws:
NotFoundException
See Also:
CtClass.getDeclaredMethod(String)

makeClass

public CtClass makeClass(java.io.InputStream classfile)
                  throws java.io.IOException,
                         java.lang.RuntimeException
Creates a new class (or interface) from the given class file. If there already exists a class with the same name, the new class overwrites that previous class.

This method is used for creating a CtClass object directly from a class file. The qualified class name is obtained from the class file; you do not have to explicitly give the name.

Parameters:
classfile - class file.
Throws:
java.lang.RuntimeException - if there is a frozen class with the the same name.
java.io.IOException
See Also:
ByteArrayClassPath

makeClass

public CtClass makeClass(java.lang.String classname)
                  throws java.lang.RuntimeException
Creates a new public class. If there already exists a class with the same name, the new class overwrites that previous class.

Parameters:
classname - a fully-qualified class name.
Throws:
java.lang.RuntimeException - if the existing class is frozen.

makeClass

public CtClass makeClass(java.lang.String classname,
                         CtClass superclass)
                  throws java.lang.RuntimeException
Creates a new public class. If there already exists a class/interface with the same name, the new class overwrites that previous class.

Parameters:
classname - a fully-qualified class name.
superclass - the super class.
Throws:
java.lang.RuntimeException - if the existing class is frozen.

makeInterface

public CtClass makeInterface(java.lang.String name)
                      throws java.lang.RuntimeException
Creates a new public interface. If there already exists a class/interface with the same name, the new interface overwrites that previous one.

Parameters:
name - a fully-qualified interface name.
Throws:
java.lang.RuntimeException - if the existing interface is frozen.

makeInterface

public CtClass makeInterface(java.lang.String name,
                             CtClass superclass)
                      throws java.lang.RuntimeException
Creates a new public interface. If there already exists a class/interface with the same name, the new interface overwrites that previous one.

Parameters:
name - a fully-qualified interface name.
superclass - the super interface.
Throws:
java.lang.RuntimeException - if the existing interface is frozen.

appendSystemPath

public ClassPath appendSystemPath()
Appends the system search path to the end of the search path. The system search path usually includes the platform library, extension libraries, and the search path specified by the -classpath option or the CLASSPATH environment variable.

Returns:
the appended class path.

insertClassPath

public ClassPath insertClassPath(ClassPath cp)
Insert a ClassPath object at the head of the search path.

Returns:
the inserted class path.
See Also:
ClassPath, URLClassPath, ByteArrayClassPath

appendClassPath

public ClassPath appendClassPath(ClassPath cp)
Appends a ClassPath object to the end of the search path.

Returns:
the appended class path.
See Also:
ClassPath, URLClassPath, ByteArrayClassPath

insertClassPath

public ClassPath insertClassPath(java.lang.String pathname)
                          throws NotFoundException
Inserts a directory or a jar (or zip) file at the head of the search path.

Parameters:
pathname - the path name of the directory or jar file. It must not end with a path separator ("/").
Returns:
the inserted class path.
Throws:
NotFoundException - if the jar file is not found.

appendClassPath

public ClassPath appendClassPath(java.lang.String pathname)
                          throws NotFoundException
Appends a directory or a jar (or zip) file to the end of the search path.

Parameters:
pathname - the path name of the directory or jar file. It must not end with a path separator ("/").
Returns:
the appended class path.
Throws:
NotFoundException - if the jar file is not found.

removeClassPath

public void removeClassPath(ClassPath cp)
Detatches the ClassPath object from the search path. The detached ClassPath object cannot be added to the pathagain.


appendPathList

public void appendPathList(java.lang.String pathlist)
                    throws NotFoundException
Appends directories and jar files for search.

The elements of the given path list must be separated by colons in Unix or semi-colons in Windows.

Parameters:
pathlist - a (semi)colon-separated list of the path names of directories and jar files. The directory name must not end with a path separator ("/").
Throws:
NotFoundException - if a jar file is not found.

toClass

public java.lang.Class toClass(CtClass clazz)
                        throws CannotCompileException
Converts the given class to a java.lang.Class object. Once this method is called, further modifications are not allowed any more. To load the class, this method uses the context class loader of the current thread. If the program is running on some application server, the context class loader might be inappropriate to load the class.

This method is provided for convenience. If you need more complex functionality, you should write your own class loader.

Throws:
CannotCompileException
See Also:
toClass(CtClass, java.lang.ClassLoader)

toClass

public java.lang.Class toClass(CtClass ct,
                               java.lang.ClassLoader loader)
                        throws CannotCompileException
Converts the class to a java.lang.Class object. Once this method is called, further modifications are not allowed any more.

The class file represented by the given CtClass is loaded by the given class loader to construct a java.lang.Class object. Since a private method on the class loader is invoked through the reflection API, the caller must have permissions to do that.

This method is provided for convenience. If you need more complex functionality, you should write your own class loader.

Parameters:
loader - the class loader used to load this class.
Throws:
CannotCompileException


Javassist, a Java-bytecode translator toolkit. Copyright (C) 1999-2005 Shigeru Chiba. All Rights Reserved.