Javassist is a class library for dealing with Java bytecode. Java bytecode is stored in a binary file called a class file. Each class file contains one Java class or interface.

The class Javassist.CtClass is an abstract representation of a class file. A CtClass (compile-time class) object is a handle for dealing with a class file. The following program is a very simple example:

ClassPool pool = ClassPool.getDefault();
CtClass cc = pool.get("test.Rectangle");
cc.setSuperclass(pool.get("test.Point"));
pool.writeFile("test.Rectangle");          // or simply, cc.writeFile()

This program first obtains a ClassPool object, which controls bytecode modification with Javassist. The ClassPool object is a container of CtClass object representing a class file. It reads a class file on demand for constructing a CtClass object and contains the constructed object until it is written out to a file or an output stream.

The ClassPool object is used to maintain one-to-one mapping between classes and CtClass objects. Javassist never allows two distinct CtClass objects to represent the same class. This is a crucial feature to consistent program transformaiton. If you need, however, you can deal with multiple instances of ClassPool at the same time. To create a new instance of ClassPool, write the following code:

ClassPool cp = new ClassPool(null);
cp.appendSystemPath();
cp.insertClassPath(".");    // or something appropriate

ClassPool.getDefault() is just a singleton factory method provided for convenience.

To modify the definition of a class, the users must first obtain a reference to the CtClass object representing that class. ClassPool.get() is used for this purpose. In the case of the program above, the CtClass object representing a class test.Rectangle is obtained from the ClassPool object and it is assigned to a variable cc. Then it is modified so that the superclass of test.Rectangle is changed into a class test.Point. This change is reflected on the original class file when ClassPool.writeFile() is finally called.

Note that writeFile() is a method declared in not CtClass but ClassPool. If this method is called, the ClassPool finds a CtClass object specified with a class name among the objects that the ClassPool contains. Then it translates that CtClass object into a class file and writes it on a local disk.

There is also writeFile() defined in CtClass. Thus, the last line in the program above can be rewritten into:

cc.writeFile();

This method is a convenient method for invoking writeFile() in ClassPool with the name of the class represented by cc.

Javassist also provides a method for directly obtaining the modified bytecode. To do this, call write():

byte[] b = pool.write("test.Rectangle");

The contents of the class file for test.Rectangle are assigned to a variable b in the form of byte array. writeFile() also internally calls write() to obtain the byte array written in a class file.

The default ClassPool returned by a static method ClassPool.getDefault() searches the same path as the underlying JVM. The users can expand this class search path if needed. For example, the following code adds a directory /usr/local/javalib to the search path:

ClassPool pool = ClassPool.getDefault();
pool.insertClassPath("/usr/local/javalib");

The search path that the users can add is not only a directory but also a URL:

ClassPool pool = ClassPool.getDefault();
ClassPath cp = new URLClassPath("www.foo.com", 80, "/java/", "com.foo.");
pool.insertClassPath(cp);

This program adds "http://www.foo.com:80/java/" to the class search path. This URL is used only for searching classes belonging to a package com.foo.

You can directly give a byte array to a ClassPool object and construct a CtClass object from that array. To do this, use ByteArrayClassPath. For example,

ClassPool cp = ClassPool.getDefault();
byte[] b = a byte array;
String name = class name;
cp.insertClassPath(new ByteArrayClassPath(name, b));
CtClass cc = cp.get(name);

The obtained CtClass object represents a class defined by the class file specified by b.

Since ClassPath is an interface, the users can define a new class implementing this interface and they can add an instance of that class so that a class file is obtained from a non-standard resource.

If you want to directly construct a CtClass object from a class file but you do not know the fully-qualified name of the class, then you can use makeClass() in CtClass:

ClassPool cp = ClassPool.getDefault();
InputStream ins = an input stream for reading a class file;
CtClass cc = cp.makeClass(ins);

makeClass() returns the CtClass object constructed from the given input stream. You can use makeClass() for eagerly feeding class files to the ClassPool object. This might improve performance if the search path includes a large jar file. Since the ClassPool object reads a class file on demand, it might repeatedly search the whole jar file for every class file. makeClass() can be used for optimizing this search. The CtClass constructed by makeClass() is kept in the ClassPool object and the class file is never read again.

To define a new class from scratch, makeClass() must be called on a ClassPool.

ClassPool pool = ClassPool.getDefault();
CtClass cc = pool.makeClass("Point");

This program defines a class Point including no members.

A new class can be also defined as a copy of an existing class. The program below does that:

ClassPool pool = ClassPool.getDefault();
CtClass cc = pool.makeClass("Point");
cc.setName("Pair");

This program first obtains the CtClass object for class Point. Then it gives a new name Pair to that CtClass object. If get("Point") is called on the ClassPool object, then a class file Point.class is read again and a new CtClass object for class Point is constructed again.

ClassPool pool = ClassPool.getDefault();
CtClass cc = pool.makeClass("Point");
CtClass cc1 = pool.get("Point");   // cc1 is identical to cc.
cc.setName("Pair");
CtClass cc2 = pool.get("Pair");    // cc2 is identical to cc.
CtClass cc3 = pool.get("Point");   // cc3 is not identical to cc.

If what classes are modified is known in advance, the easiest way for modifying the classes is as follows:

• 1. Get a CtClass object by calling ClassPool.get(),
• 2. Modify it, and
• 3. Call ClassPool.write() or writeFile().

If whether a class is modified or not is determined at load time, the users can write an event listener so that it is notified when a class is loaded into the JVM. A class loader (java.lang.ClassLoader) working with Javassist must call ClassPool.write() for obtaining a class file. The users can write an event listener so that it is notified when the class loader calls ClassPool.write(). The event-listener class must implement the following interface:

public interface Translator {
    public void start(ClassPool pool)
        throws NotFoundException, CannotCompileException;
    public void onWrite(ClassPool pool, String classname)
        throws NotFoundException, CannotCompileException;
}

The method start() is called when this event listener is registered to a ClassPool object. The method onWrite() is called when write() (or similar methods) is called on the ClassPool object. The second parameter of onWrite() is the name of the class to be written out.

Note that start() or onWrite() do not have to call write() or writeFile(). For example,

public class MyAnotherTranslator implements Translator {
    public void start(ClassPool pool)
        throws NotFoundException, CannotCompileException {}
    public void onWrite(ClassPool pool, String classname)
        throws NotFoundException, CannotCompileException
    {
        CtClass cc = pool.get(classname);
        cc.setModifiers(Modifier.PUBLIC);
    }
}

All the classes written out by write() are made public just before their definitions are translated into an byte array.

The two methods start() and onWrite() can modify not only a CtClass object specified by the given classname but also any CtClass objects contained in the given ClassPool. They can call ClassPool.get() for obtaining any CtClass object. If a modified CtClass object is not written out immediately, the modification is recorded until that object is written out.

To register an event listener to a ClassPool, it must be passed to a constructor of ClassPool. Only a single event listener can be registered. If more than one event listeners are needed, multiple ClassPools should be connected to be a single stream. For example,

Translator t1 = new MyTranslator();
ClassPool c1 = new ClassPool(t1);
Translator t2 = new MyAnotherTranslator();
ClassPool c2 = new ClassPool(c1, t2);

This program connects two ClassPools. If a class loader calls write() on c2, the specified class file is first modified by t1 and then by t2. write() returns the resulting class file. First, onWrite() on t1 is called since c2 obtains a class file by calling write() on c1. Then onWrite() on t2 is called. If onWrite() called on t2 obtains a CtClass object from c2, that CtClass object represents the class file that t1 has modified.

Javassist can be used with a class loader so that bytecode can be modified at load time. The users of Javassist can define their own version of class loader but they can also use a class loader provided by Javassist.

Using a class loader is not easy. Especially if you are a beginner, you should separate your program into an application program and an instrumentation program and each of the two programs should be loaded by a single class loader. You should avoid loading part of the application program with the default class loader and the rest of the program with a user-defined class loader.

4.1 Using javassist.Loader

Javassist provides a class loader javassist.Loader. This class loader uses a javassist.ClassPool object for reading a class file.

For example, javassist.Loader can be used for loading a particular class modified with Javassist.

import javassist.*;
import test.Rectangle;

public class Main {
  public static void main(String[] args) throws Throwable {
     ClassPool pool = ClassPool.getDefault();
     Loader cl = new Loader(pool);

     CtClass ct = pool.get("test.Rectangle");
     ct.setSuperclass(pool.get("test.Point"));

     Class c = cl.loadClass("test.Rectangle");
     Object rect = c.newInstance();
         :
  }
}

This program modifies a class test.Rectangle. The superclass of test.Rectangle is set to a test.Point class. Then this program loads the modified class into the JVM, and creates a new instance of the test.Rectangle class.

The users can use a javassist.Translator object for modifying class files. Suppose that an instance of a class MyTranslator, which implements javassist.Translator, performs modification of class files. To run an application class MyApp with the MyTranslator object, write a main class:

import javassist.*;

public class Main2 {
  public static void main(String[] args) throws Throwable {
     Translator t = new MyTranslator();
     ClassPool pool = ClassPool.getDefault(t);
     Loader cl = new Loader(pool);
     cl.run("MyApp", args);
  }
}

To run this program, do:

% java Main arg1 arg2...

The class MyApp and the other application classes are translated by MyTranslator.

Note that application classes like MyApp cannot access the loader classes such as Main, MyTranslator and ClassPool because they are loaded by different loaders. The application classes are loaded by javassist.Loader whereas the loader classes such as Main are by the default Java class loader.

In Java, for security reasons, a single class file may be loaded into the JVM by two distinct class loaders so that two different classes would be created. For example,

class Point {
    int x, y;
}

class Box {
    Point base;
    Point getBase() { return base; }
}

class Window {
    Point size;
    Point getSize() { return size; }
}

Suppose that a class Box is loaded by a class loader L1 while a class Window is loaded by a class loader L2. Then, the obejcts returned by getBase() and getSize() are not instances of the same class Point. getBase() returns an instance of the class Point loaded by L1 whereas getSize() returns an instance of Point loaded by L2. The two versions of the class Point are distinct. They belong to different name spaces. For more details, see the following paper:

Sheng Liang and Gilad Bracha, "Dynamic Class Loading in the Java Virtual Machine",
ACM OOPSLA'98, pp.36-44, 1998.

To avoid this problem, the two class loaders L1 and L2 must delegate the loading operation of the class Point to another class loader, L3, which is a parent class loader of L1 and L2. delegateLoadingOf() in javassist.Loader is a method for specifying what classes should be loaded by the parent loader.

If L1 is the parent class loader of L2, that is, if L1 loads the class of L2, then L2 can delegate the loading operation of Point to L1 for avoiding the problem above. However, this technique does not work in the case below:

class Point {     // loaded by L1
    Window win;
    int x, y;
}

class Box {       // loaded by L1
    Point base;
    Point getBase() { return base; }
}

class Window {    // loaded by L2
    Point size;
    Point getSize() { size.win = this; return size; }
}

Since all the classes included in a class definition loaded by a class loader L1 are also loaded by L1, the class of the field win in Point is now the class Window loaded by L1. Thus size.win = this in getSize() raises a runtime exception because of type mismatch; the type of size.win is the class Point loaded by L1 whereas the type of this is the class Point loaded by L2.

javassist.Loader searches for classes in a different order from java.lang.ClassLoader. ClassLoader first delegates the loading operations to the parent class loader and then attempts to load the classes only if the parent class loader cannot find them. On the other hand, javassist.Loader attempts to load the classes before delegating to the parent class loader. It delegates only if:

• the classes are not found by using the ClassPool object, or

• the classes have been specified by using delegateLoadingOf() to be loaded by the parent class loader.

This search order allows loading modified classes by Javassist into the JVM. However, it delegates to the parent class loader if it fails to find modified classes for some reason. Once a class is loaded by the parent class loader, the other classes used by that class will be also loaded without modification by the parent class loader. If your program fails to load a modified class, you should make sure whether all the classes using that class have been loaded by javassist.Loader.

4.2 Writing a class loader

A simple class loader using Javassist is as follows:

import javassist.*;

public class SimpleLoader extends ClassLoader {
    /* Call MyApp.main().
     */
    public static void main(String[] args) throws Throwable {
        SimpleLoader s = new SimpleLoader();
        Class c = s.loadClass("MyApp");
        c.getDeclaredMethod("main", new Class[] { String[].class })
         .invoke(null, new Object[] { args });
    }

    private ClassPool pool;

    public SimpleLoader() throws NotFoundException {
        pool = ClassPool.getDefault();
        pool.insertClassPath("./class"); // MyApp.class must be there.
    }

    /* Finds a specified class.
     * The bytecode for that class can be modified.
     */
    protected Class findClass(String name) throws ClassNotFoundException {
        try {
            CtClass cc = pool.get(name);
            // modify the CtClass object here
            byte[] b = pool.write(name);
            return defineClass(name, b, 0, b.length);
        } catch (NotFoundException e) {
            throw new ClassNotFoundException();
        } catch (IOException e) {
            throw new ClassNotFoundException();
        } catch (CannotCompileException e) {
            throw new ClassNotFoundException();
        }
    }
}

The class MyApp is an application program. To execute this program, first put the class file under the ./class directory, which must not be included in the class search path. The directory name is specified by insertClassPath() in the constructor. You can choose a different name instead of ./class if you want. Then do as follows:

% java SimpleLoader

The class loader loads the class MyApp (./class/MyApp.class) and calls MyApp.main() with the command line parameters. Note that MyApp.class must not be under the directory that the system class loader searches. Otherwise, the system class loader, which is the parent loader of SimpleLoader, loads the class MyApp.

This is the simplest way of using Javassist. However, if you write a more complex class loader, you may need detailed knowledge of Java's class loading mechanism. For example, the program above puts the MyApp class in a name space separated from the name space that the class SimpleLoader belongs to because the two classes are loaded by different class loaders. Hence, the MyApp class cannot directly access the class SimpleLoader.

4.3 Modifying a system class

The system classes like java.lang.String cannot be loaded by a class loader other than the system class loader. Therefore, SimpleLoader or javassist.Loader shown above cannot modify the system classes at loading time.

If your application needs to do that, the system classes must be statically modified. For example, the following program adds a new field hiddenValue to java.lang.String:

ClassPool pool = ClassPool.getDefault();
CtClass cc = pool.get("java.lang.String");
cc.addField(new CtField(CtClass.intType, "hiddenValue", cc));
pool.writeFile("java.lang.String", ".");

This program produces a file "./java/lang/String.class".

To run your program MyApp with this modified String class, do as follows:

% java -Xbootclasspath/p:. MyApp arg1 arg2...

Suppose that the definition of MyApp is as follows:

public class MyApp {
    public static void main(String[] args) throws Exception {
        System.out.println(String.class.getField("hiddenValue").getName());
    }
}

If the modified String class is correctly loaded, MyApp prints hiddenValue.

Note: Applications that use this technique for the purpose of overriding a system class in rt.jar should not be deployed as doing so would contravene the Java 2 Runtime Environment binary code license.