classUtils.javassist
Class ClassPool

java.lang.Object
  classUtils.javassist.ClassPool

public class ClassPool
extends java.lang.Object

A driver class for controlling bytecode editing with Javassist. It manages where a class file is obtained and how it is modified.

A ClassPool object can be regarded as a container of CtClass objects. It reads class files on demand from various sources represented by ClassPath and create CtClass objects representing those class files. The source may be another ClassPool. If so, write() is called on the source ClassPool for obtaining a class file.

A CtClass object contained in a ClassPool is written to an output stream (or a file) if write() (or writeFile()) is called on the ClassPool. write() is typically called by a class loader, which obtains the bytecode image to be loaded.

The users can modify CtClass objects before those objects are written out. To obtain a reference to a CtClass object contained in a ClassPool, get() should be called on the ClassPool. If a CtClass object is modified, then the modification is reflected on the resulting class file returned by write() in ClassPool.

In summary,

• get() returns a reference to a CtClass object contained in a ClassPool.

• write() translates a CtClass object contained in a ClassPool into a class file and writes it to an output stream.

The users can add a listener object receiving an event from a ClassPool. An event occurs when a listener is added to a ClassPool and when write() is called on a ClassPool. The listener class must implement Translator. A typical listener object is used for modifying a CtClass object on demand when it is written to an output stream.

The implementation of this class is thread-safe.

See Also:

CompileTimeClass, ClassPath, Translator

Constructor Summary

ClassPool(ClassPool src)
Creates a class pool.

ClassPool(ClassPool src, Translator trans)
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.
void	debugWriteFile(java.lang.String classname) Writes a class file specified with classname in the current directory.
void	debugWriteFile(java.lang.String classname, java.lang.String directoryName) Writes a class file specified with classname.
static java.lang.Class	forName(java.lang.String name) Returns a java.lang.Class object that has been loaded by writeAsClass().
CompileTimeClass	get(java.lang.String classname) Reads a class file from the source and returns a reference to the CtClass object representing that class file.
CompileTimeClass[]	get(java.lang.String[] classnames) Reads class files from the source and returns an array of CtClass objects representing those class files.
CompileTimeClass	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.
static ClassPool	getDefault(Translator t) Returns the default class pool.
java.lang.String	getFile(java.lang.String className)
CtMethod	getMethod(java.lang.String classname, java.lang.String methodname) Reads a class file and obtains a compile-time method.
Translator	getTranslator() Returns the Translator object associated with this ClassPool.
ClassPath	insertClassPath(ClassPath cp) Insert a ClassPath object affineTransform the head of the search path.
ClassPath	insertClassPath(java.lang.String pathname) Inserts a directory or a jar (or zip) file affineTransform the head of the search path.
java.lang.Object[]	lookupCflow(java.lang.String name) Undocumented method.
CompileTimeClass	makeClass(java.io.InputStream classfile) Creates a new class from the given class file.
CompileTimeClass	makeClass(java.lang.String classname) Creates a new public class.
CompileTimeClass	makeClass(java.lang.String classname, CompileTimeClass superclass) Creates a new public class.
CompileTimeClass	makeInterface(java.lang.String name) Creates a new public interface.
CompileTimeClass	makeInterface(java.lang.String name, CompileTimeClass superclass) Creates a new public interface.
void	removeClassPath(ClassPath cp) Detatches the ClassPath object from the search path.
java.lang.String	toString() Returns the class search path.
byte[]	write(java.lang.String classname) Returns a byte array representing the class file.
void	write(java.lang.String classname, java.io.DataOutputStream out) Writes a class file specified by classname to a given output stream.
java.lang.Class	writeAsClass(java.lang.String classname) Returns a java.lang.Class object.
void	writeFile(java.lang.String classname) Writes a class file specified with classname in the current directory.
void	writeFile(java.lang.String classname, java.lang.String directoryName) Writes a class file specified with classname on a local disk.

Methods inherited from class java.lang.Object

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

Constructor Detail

ClassPool

public ClassPool(ClassPool src)

Creates a class pool.

Parameters:

src - the source of class files. If it is null, the class search path is initially null.

See Also:

getDefault()

ClassPool

public ClassPool(ClassPool src,
                 Translator trans)
          throws java.lang.RuntimeException

Creates a class pool.

Parameters:

src - the source of class files. If it is null, the class search path is initially null.

trans - the translator linked to this class pool. It may be null.

Throws:

java.lang.RuntimeException

See Also:

getDefault()

Method Detail

getDefault

public static ClassPool getDefault(Translator t)

Returns the default class pool. The returned object is always identical.

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.

Parameters:

t - null or the translator linked to the class pool.

getDefault

public static ClassPool getDefault()

Returns the default class pool. The returned object is always identical.

This returns the result of getDefault(null).

See Also:

getDefault(Translator)

toString

public java.lang.String toString()

Returns the class search path.

Overrides:

toString in class java.lang.Object

getTranslator

public Translator getTranslator()

Returns the Translator object associated with this ClassPool.

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

debugWriteFile

public void debugWriteFile(java.lang.String classname)
                    throws NotFoundException,
                           CannotCompileException,
                           java.io.IOException

Writes a class file specified with classname in the current directory. It never calls onWrite() on a translator. It is provided for debugging.

Parameters:

classname - the name of the class written on a local disk.

Throws:

NotFoundException

CannotCompileException

java.io.IOException

debugWriteFile

public void debugWriteFile(java.lang.String classname,
                           java.lang.String directoryName)
                    throws NotFoundException,
                           CannotCompileException,
                           java.io.IOException

Writes a class file specified with classname. It never calls onWrite() on a translator. It is provided for debugging.

Parameters:

classname - the name of the class written on a local disk.

directoryName - it must end without a directory separator.

Throws:

NotFoundException

CannotCompileException

java.io.IOException

writeFile

public void writeFile(java.lang.String classname)
               throws NotFoundException,
                      CannotCompileException,
                      java.io.IOException

Writes a class file specified with classname in the current directory. It calls onWrite() on a translator.

Parameters:

classname - the name of the class written on a local disk.

Throws:

NotFoundException

CannotCompileException

java.io.IOException

writeFile

public void writeFile(java.lang.String classname,
                      java.lang.String directoryName)
               throws NotFoundException,
                      CannotCompileException,
                      java.io.IOException

Writes a class file specified with classname on a local disk. It calls onWrite() on a translator.

Parameters:

classname - the name of the class written on a local disk.

directoryName - it must end without a directory separator.

Throws:

NotFoundException

CannotCompileException

java.io.IOException

forName

public static java.lang.Class forName(java.lang.String name)
                               throws java.lang.ClassNotFoundException

Returns a java.lang.Class object that has been loaded by writeAsClass(). That object cannot be obtained by java.lang.Class.forName() because it has been loaded by an internal class loader of Javassist.

Throws:

java.lang.ClassNotFoundException

See Also:

writeAsClass(String), CompileTimeClass.toClass()

getFile

public java.lang.String getFile(java.lang.String className)
                         throws NotFoundException

Throws:

NotFoundException

writeAsClass

public java.lang.Class writeAsClass(java.lang.String classname)
                             throws NotFoundException,
                                    java.io.IOException,
                                    CannotCompileException

Returns a java.lang.Class object. It calls write() to obtain a class file and then loads the obtained class file into the JVM. The returned Class object represents the loaded class.

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

To load a class file, this method uses an internal class loader. Thus, that class file is not loaded by the system class loader, which should have loaded this ClassPool class. The internal class loader loads only the classes explicitly specified by this method writeAsClass(). The other classes are loaded by the parent class loader (the sytem class loader) by delegation.

For example,

class Line { Point p1, p2; }

If the class Line is loaded by the internal class loader and the class Point has not been loaded yet, then the class Point that the class Line refers to is loaded by the parent class loader. There is no chance of modifying the definition of Point with Javassist.

The internal class loader is shared among all the instances of ClassPool.

Parameters:

classname - a fully-qualified class name.

Throws:

NotFoundException

java.io.IOException

CannotCompileException

See Also:

forName(String), CompileTimeClass.toClass(), Loader

write

public byte[] write(java.lang.String classname)
             throws NotFoundException,
                    java.io.IOException,
                    CannotCompileException

Returns a byte array representing the class file. It calls onWrite() on a translator.

Parameters:

classname - a fully-qualified class name.

Throws:

NotFoundException

java.io.IOException

CannotCompileException

write

public void write(java.lang.String classname,
                  java.io.DataOutputStream out)
           throws NotFoundException,
                  CannotCompileException,
                  java.io.IOException

Writes a class file specified by classname to a given output stream. It calls onWrite() on a translator.

This method does not close the output stream in the end.

Parameters:

classname - a fully-qualified class name.

out - an output stream

Throws:

NotFoundException

CannotCompileException

java.io.IOException

getAndRename

public CompileTimeClass 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 that class file has been already loaded and the resulting class is frozen.

Parameters:

orgName - the original (fully-qualified) class name

newName - the new class name

Throws:

NotFoundException

get

public CompileTimeClass 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 affineTransform the first time.

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

Parameters:

classname - a fully-qualified class name.

Throws:

NotFoundException

get

public CompileTimeClass[] 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:

CompileTimeClass.getDeclaredMethod(String)

makeClass

public CompileTimeClass makeClass(java.io.InputStream classfile)
                           throws java.io.IOException,
                                  java.lang.RuntimeException

Creates a new class 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

makeClass

public CompileTimeClass 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 CompileTimeClass makeClass(java.lang.String classname,
                                  CompileTimeClass 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 CompileTimeClass 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 CompileTimeClass makeInterface(java.lang.String name,
                                      CompileTimeClass 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 affineTransform 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 affineTransform 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.