Getting Started with Javassist

Shigeru Chiba

Next page


1. Reading bytecode

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:

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 unless two independent ClassPool are created. This is a significant feature for consistent program transformaiton. To create multiple instances of ClassPool, write the following code:

This creates a ClassPool object that behaves as the default ClassPool returned by ClassPool.getDefault() does. ClassPool.getDefault() is a singleton factory method provided for convenience.

If you have two ClassPool objects, then you can obtain, from each ClassPool, a distinct CtClass object representing the same class file. You can differently modify these CtClass objects to generate different versions of the class.

To modify the definition of a class, the users must first obtain a reference to the CtClass object representing that class. get() in ClassPool is used for this purpose. In the case of the program shown at the beginning, 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 writeFile() in CtClass() is finally called.

writeFile() translates the CtClass object into a class file and writes it on a local disk. Javassist also provides a method for directly obtaining the modified bytecode. To obtain the bytecode, call toBytecode():

The default ClassPool returned by a static method ClassPool.getDefault() searches the same path that the underlying JVM (Java virtual machine) has. 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:

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

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

Furthermore, 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,

The obtained CtClass object represents a class defined by the class file specified by b. The ClassPool reads a class file from the given ByteArrayClassPath if get() is called and the class name given to get() is equal to one specified by name.

If you do not know the fully-qualified name of the class, then you can use makeClass() in ClassPool:

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 a 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.

The users can extend the class search path. They can define a new class implementing ClassPath interface and give an instance of that class to insertClassPath() in ClassPool. This allows a non-standard resource to be included in the search path.


2. Defining a new class

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

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:

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 later called on the ClassPool object again, then a class file Point.class is read again and a new CtClass object for class Point is constructed again. See the followings:

Once a CtClass object is converted into a class file by writeFile() or toBytecode(), Javassist rejects further modifications of that CtClass object. Hence, after the CtClass object representing Point class is converted into a class file, you cannot define Pair class as a copy of Point since executing setName() on Point is rejected.

To avoid this restriction, you should call getAndRename() in ClassPool. For example,

If getAndRename() is called, the ClassPool reads Point.class for creating a new CtClass object representing Pair class. getAndRename() can be executed after writeFile() or toBytecode() is called on the the ClassPool representing Point class.


3. ClassPool

A ClassPool object is a container of CtClass objects. Once a CtClass object is created, it is recorded in a ClassPool for ever. This is because a compiler may need to access the CtClass object later when it compiles source code that refers to the class represented by that CtClass. If the class definition represented by that CtClass object is different from that of the original class file, the compiler cannot correctly compile the source code without the CtClass object.

This specification of ClassPool may cause huge memory consumption if the number of CtClass objects becomes large. To avoid this problem, you can explicitly remove an unnecessary CtClass object from the ClassPool. If you call detach() on a CtClass object, then that CtClass object is removed from the ClassPool. For example,

You must not call any method on that CtClass object after detach() is called.

ClassPool objects can be cascaded like java.lang.ClassLoader. For example,

If child.get() is called, the child ClassPool first delegates to the parent ClassPool. If the parent ClassPool fails to find a class file, then the child ClassPool attempts to find a class file. If child.childFirstLookup is true, the child ClassPool attempts to find a class file before delegating to the parent ClassPool. For example,


4. Class loader

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

If whether a class is modified or not is determined at load time, the users must make Javassist collaborate with a class loader. 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. In particular, if you are a beginner, you should separate your program into an application program and an instrumentation program. Then you should load only the former program by a user-defined class loader. The latter one, as well as the program of the user-defined class loader, should be loaded by the system class loader.


4.1 Class loading in Java

In Java, multiple class loaders can coexist and each class loader creates its own name space. Different class loaders can load different class files with the same class name. The loaded two classes are regarded as different ones. This feature enables us to run multiple application programs on a single JVM.

If the same class file is loaded by two distinct class loaders, the JVM makes two distinct classes with the same name and definition. The two classes are regarded as different ones. Since the two classes are not identical, an instance of one class is not assignable to a variable of the other class. The cast operation between the two classes fails and throws a ClassCastException.

Multiple class loaders form a tree structure. Each class loader except the bootstrap loader has a parent class loader, which has normally loaded the class of that child class loader. Since the request to load a class can be delegated along this hierarchy of class loaders, a class may be loaded by a class loader that you do not request the class loading. Therefore, the class loader that has been requested to load a class C may be different from the loader that actually loads the class C. For distinction, we call the former loader the initiator of C and we call the latter loader the real loader of C.

Furthermore, if a class loader CL requested to load a class C (the initiator of C) delegates to the parent class loader PL, then the class loader CL is never requested to load any classes referred to in the definition of the class C. CL is not the initiator of those classes. Instead, the parent class loader PL becomes their initiators and it is requested to load them. The classes that the definition of a class C referes to are loaded by the real loader of C.

To understand this behavior, let's consider the following example.

Suppose that a class Window is loaded by a class loader L. Both the initiator and the real loader of Window are L. Since the definition of Window refers to Box, the JVM will request L to load Box. Here, suppose that L delegates this task to the parent class loader PL. The initiator of Box is L but the real loader is PL. In this case, the initiator of Point is not L but PL since it is the same as the real loader of Box. Thus L is never requested to load Point.

Next, let's consider a slightly modified example.

Now, the definition of Window also refers to Point. In this case, the class loader L must also delegate to PL if it is requested to load Point. You must avoid having two class loaders doubly load the same class. One of the two loaders must delegate to the other.

If L does not delegate to PL when Point is loaded, widthIs() would throw a ClassCastException. Since the real loader of Box is PL, Point referred to in Box is also loaded by PL. Therefore, the resulting value of getSize() is an instance of Point loaded by PL whereas the type of the variable p in widthIs() is Point loaded by L. The JVM regards them as distinct types and thus it throws an exception because of type mismatch.

This behavior is somewhat inconvenient but necessary. If the following statement:

did not throw an exception, then the programmer of Window could break the encapsulation of Point objects. For example, the field x is private in Point loaded by PL. However, the Window class could directly access the value of x if L loads Point with the following definition:

For more details of class loaders in Java, the following paper would be helpful:


4.2 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.

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, and creates a new instance of the test.Rectangle class.

If the users want to modify a class on demand when it is loaded, the users can add an event listener to a javassist.Loader. The added event listener is notified when the class loader loads a class. The event-listener class must implement the following interface:

The method start() is called when this event listener is added to a javassist.Loader object by addTranslator() in javassist.Loader. The method onWrite() is called before javassist.Loader loads a class. onWrite() can modify the definition of the loaded class.

For example, the following event listener changes all classes to public classes just before they are loaded.

Note that onWrite() does not have to call toBytecode() or writeFile() since javassist.Loader calls these methods to obtain a class file.

To run an application class MyApp with a MyTranslator object, write a main class as following:

To run this program, do:

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 Main2, 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.

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:

This search order allows loading modified classes by Javassist. 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 referred to in that class will be also loaded by the parent class loader and thus they are never modified. Recall that all the classes referred to in a class C are loaded by the real loader of C. 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.3 Writing a class loader

A simple class loader using Javassist is as follows:

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. Otherwise, MyApp.class would be loaded by the default system class loader, which is the parent loader of SampleLoader. The directory name ./class is specified by insertClassPath() in the constructor. You can choose a different name instead of ./class if you want. Then do as follows:

The class loader loads the class MyApp (./class/MyApp.class) and calls MyApp.main() with the command line parameters.

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 SampleLoader belongs to because the two classes are loaded by different class loaders. Hence, the MyApp class cannot directly access the class SampleLoader.


4.4 The toClass method in CtClass

The CtClass provides a convenience method toClass, which loads the class by an internal class loader of Javassist. This method first obtains the class file representing the modified class and loads it by an instance of javassist.ClassPool.SimpleLoader. The following code is the definition of this class loader:

loadClass() loads the class specified by classfile. Thus, toClass() is equivalent to the following code:

Note that this class loader might be too simple for realistic use. It delegates to the parent class loader unless the class is explicitly loaded by loadClass() (or toClass() in CtClass). If you encounter an unexpected ClassCastException, you should check the class loader of the object. Call getClass().getClassLoader() on the object and make sure that the destination class and the source class of the cast operation have been loaded by the same class loader.


4.5 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, SampleLoader 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:

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

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

Suppose that the definition of MyApp is as follows:

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.


Next page


Java(TM) is a trademark of Sun Microsystems, Inc.
Copyright (C) 2000-2004 by Shigeru Chiba, All rights reserved.