Javassist Documentation

Javassist (JAVA programming ASSISTant) is a Java bytecode engineering toolkit used for manipulating Java bytecode. It allows Java programs to define new classes at runtime and modify existing class files when the JVM loads them.

Javassist provides two distinct API levels:

1. Source-level API: Allows editing class files using standard Java language vocabulary without needing knowledge of bytecode specifications. You can specify inserted bytecode as source text, which Javassist compiles on the fly.
2. Bytecode-level API: Allows for direct editing of class files, similar to other bytecode editors.

You can print the version number of the installed Javassist library by running the jar file directly with the java command.

java -jar javassist.jar

If you have Apache Ant installed, you can run all sample tasks at once using the sample-all target.

Note: All programs are for demonstration only and are not intended for production use. JDK 1.4 or later is required.

% ant sample-all

The Bytecode class is a utility for producing a bytecode sequence. It acts as an unbounded array containing bytecode and is used to build the CodeAttribute for a class. You can append various instructions (opcodes), constants, and method calls to the sequence.

To use it, construct a Bytecode object with a ConstPool, append instructions using the provided add... methods, and finally convert it to a CodeAttribute using toCodeAttribute().

ConstPool cp = ...;    // constant pool table
Bytecode b = new Bytecode(cp, 1, 0);
b.addIconst(3);
b.addReturn(CtClass.intType);
CodeAttribute ca = b.toCodeAttribute();

To interact with the members of a class, use these methods:

• getFields(): Returns an array of all accessible fields (including inherited ones).
• getDeclaredFields(): Returns an array of fields declared specifically in this class.
• getField(String name, String desc): Retrieves a specific field by name and descriptor.
• getConstructors(): Returns an array of public constructors.
• getDeclaredBehaviors(): Returns an array containing both constructors and methods declared in this class.

The CodeAnalyzer class provides utility methods to analyze bytecode instructions and control flow, specifically for computing the max_stack value required for a method's attribute.

To use it, instantiate CodeAnalyzer with a CodeAttribute object and call computeMaxStack().

Use the following methods to retrieve information about entries in the ExceptionTable by their index (nth):

• size(): Returns the number of entries in the table.
• startPc(int nth): Returns the start program counter of the $n$-th entry.
• endPc(int nth): Returns the end program counter of the $n$-th entry.
• handlerPc(int nth): Returns the handler program counter of the $n$-th entry.
• catchType(int nth): Returns an index into the constant pool table, or zero if the handler is for all exceptions.

You can manipulate class-level attributes (metadata) using the following methods:

• Get an attribute: Use getAttribute(String name) to retrieve the byte array associated with a specific attribute name.
• Set an attribute: Use setAttribute(String name, byte[] data) to add or update an attribute.

You can initialize a Bytecode object in two ways:

1. With stack and local variable limits: Specify the initial max_stack and max_locals.
2. With only a constant pool: Initializes max_stack and max_locals to zero.

Note that max_stack may be automatically updated when instructions are appended via addOpcode(), but max_locals usually needs to be set explicitly or via setMaxLocals(boolean isStatic, CtClass[] params, int locals).