Overview | Package | Class | Use | Tree | Deprecated | Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javassist
Class ClassPool

    java.lang.Object
      |
      +--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:
  `CtClass`, `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()`.
`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.
`static ClassPool` | `getDefault(Translator t)` 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.
`Translator` | `getTranslator()` Returns the `Translator` object associated with this `ClassPool`.
`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 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` | `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.
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.
    `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.
    `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.
    `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.
    `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.

    `java.lang.ClassNotFoundException`
  See Also:
    `writeAsClass(String)`, `CtClass.toClass()`

### 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.
    `NotFoundException`
    `java.io.IOException`
    `CannotCompileException`
  See Also:
    `forName(String)`, `CtClass.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.
    `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
    `NotFoundException`
    `CannotCompileException`
    `java.io.IOException`

### 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 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
    `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.

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

### 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.
    `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
    `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 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 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.

Overview | Package | Class | Use | Tree | Deprecated | Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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