Using the ASM Toolkit for Bytecode Manipulation

Sometimes Java developers need to generate or change Java bytecode in the runtime.
Is can be necessary for AOP or debugging, or even for performance optimization.
There are several frameworks available that provide different level of abstraction
for runtime code generation. One of the oldest bytecode manipulation frameworks,
Byte Code Engineering Library (BCEL),
is used in a number of projects; however, it is rather difficult to learn and use. It is also adds significant
overhead to memory and processor usage for runtime code transformations.

The ASM bytecode manipulation framework
has been designed and implemented to be small and as fast as possible.
ASM's runtime .jar is only 25KB, compared to 350KB for BCEL.
The load time overhead caused by class transformation with ASM is about 60 percent with ASM,
compared to 700 percent or more with BCEL. These factors have been
recognized by the Java community and several well known projects have switched to ASM, such as
CGLIB and
AspectWerkz.
The list of projects that are using form the beginning ASM also includes
Speedo,
Groovy,
dynaop,
BeanShell, and a
number of others.

To achieve such performance, ASM's design is based on an event-driven model.
If you are familiar with the SAX API for XML
processing, it will be easy to get into ASM, which uses a
Visitor pattern
to avoid representing visited structures with objects. Visitors receive events for particular pieces of the structure from the event generator. In SAX, XMLReader is the most commonly used event generator.
ASM framework provides a similar ClassReader class, which
knows how to parse Java bytecode from existing classes and how to fire
appropriate events to the underlying visitors. This flow of events can be also generated manually,
as we'll see in the next section.

All possible events are defined by the ClassVisitor and CodeVisitor interfaces.
The order of events is very important. Custom visitors can hook up into the flow of events and change it in order to implement bytecode transformations. ClassAdapter and CodeAdapter provide an empty implementation of the ClassVisitor and CodeVisitor interfaces and delegate all events to the linked visitor. Custom visitors can be inherited from these classes and override necessary methods and change event flow before delegating it to the next visitor. Usually, events end up in the ClassWriter and CodeWriter classes, which know how to convert a chain of events back into bytecode. Those two classes are sufficient to generate bytecode
from scratch.

Bytecode Generation

Let's look at a simple example. Imagine that you need to generate bytecode for the Notifier interface,
which would be compiled from following Java code.

In this example, ClassWriter is receiving manually crafted events and
creating corresponding bytecode. Notice the internal representation
of the class name in the visit() method and the method descriptor in
visitMethod(). Construction of such values is a common task
in bytecode generation. Fortunately, the Type class provides
several helper methods for this:

getDescriptor(Class) converts a class name into bytecode representation.

getMethodDescriptor(Type, Type[]) constructs a method descriptor. For example, a descriptor for the addListener() method could be created using the code below.

Ideally, it is good to have an understanding of the bytecode structure and JVM opcodes (see the Resources section below), but it is possible to start digging in even without such knowledge.
ASM includes an utility class that can take a .class file and create Java source code
that, when compiled, will produce an equivalent ASM-generated class. So you can compile Notifier.java and then use the command

asmifier.cmd Notifier.class

to generate equivalent code to that shown above.

Here is what asmifier.cmd looks like:

set cp=%cp%;%ASM_HOME%\asm.jar
set cp=%cp%;%ASM_HOME%\asm-attrs.jar
set cp=%cp%;%ASM_HOME%\asm-util.jar
set c=org.objectweb.asm.util.ASMifierClassVisitor
java -cp %cp% %c% %1

ASM Overview

Before looking at bytecode transformation, we need a better understanding
of the events defined for the ClassVisitor interface.

These events should come in the following order and contain parameters as described below.

Field access flags, name and signature, init value, and field attributes (e.g., annotations).

visitMethod

Method access flags, name and signature and method attributes.

visitInnerClass

Inner class access flags, its name and outer name

visitAttribute

Class-level attributes

Once

visitEnd

Complete processing

visitMethod is different from the others, because it returns a new instance of
CodeVisitor for every call. That instance will
handle processing events for method bytecode (including method and parameter
attributes, information for try-catch blocks, etc.).

The table below outlines the methods of CodeVisitor.
These methods must be called in the sequential order of the
bytecode instructions of the visited code. Each method can either handle bytecode instructions
grouped by the similar parameters or other bytecode artifacts, such as the local variable table,
line numbers, try-catch blocks, and nonstandard attributes (marked grey in the table below).

Visits the maximum stack size and the maximum number of local variables of the method.

visitAttribute

Visits a non-standard attribute of the code.

The visitMaxs method is called
after all of the instructions have been visited. The visitTryCatchBlock,
visitLocalVariable, and visitLineNumber methods may be
called in any order, at any time (provided the labels passed as arguments have
already been visited with visitLabel).

In order to specify positions in the method bytecode and not have to use absolute
offsets, ASM uses the Label class. Label instances
are passed as parameters of visitJumpInsn,
visitLookupSwitchInsn, visitTableSwitchInsn,
visitTryCatchBlock, visitLocalVariable, and visitLineNumber,
to refer to a specific place in method code; a visitLabel method with the
same Label instance is used to actually mark that place.

The next section shows how the ClassVisitor and CodeVisitor
interfaces can work together in a bytecode transformation scenario.

Bytecode Transformation

Imagine that we need to transform some classes in the runtime, and implement
the Notifier interface from the example above. In our case,
all registered observers should receive events when any of the methods
of the original class have been called. We can pick some simple class and
use ASMifierClassVisitor to see what the transformation
should look like.

Now you can compile both sources, run ASMifierClassVisitor as described
above, and then compare the resulting files using your favorite diff application.
Here are the comparison results. Removed lines are shown in red with
a minus sign (-) at the left, while additions are shown in green with
a plus sign (+).

Some instructions were added to the end of the <init> method,
representing code for constructor and class initialization.

visitMaxs() have different parameters (used stack has
been changed in modified bytecode).

Some instructions were added to the beginning of existing class methods.

Two new methods were added.

Let's take them one by one, but I should remind you that ASM's visitors can be chained very much the same way as SAX's handlers or filters. This sequence UML diagram shows class transformation, where green classes will be substituted by custom NotifierClassVisitor and NotifierCodeVisitor that will do the
actual bytecode transformation.

The code below uses NotifierClassVisitor to apply all required transformations.

Notice the true parameter in the ClassWriter constructor,
which enables the automatic calculation of maximum size of stack and local variables.
In this case, all values passed to the CodeVisitor.visitMax() method
will be ignored and ClassWriter will calculate these values
based on the actual bytecode of the method. However, the CodeVisitor.visitMax()
method still must be called, which happens in its default implementation in
CodeAdapter. This is important because, as you can see in the comparison
results, these values are different for changed bytecode, and with this flag
they will be recalculated automatically, covering item #6 in the list above.
The rest of items will be handled by NotifierClassVisitor.

The first difference appears in parameters of the visit method,
where the new interface should be added. The code below will cover item #1.
Notice that the cv.visit() method is called to redirect
the transformed processing event to the nested class visitor, which is
actually going to be a ClassWriter object.
We also need to save the class name, since it will be needed later.

All new elements can be added in the visitEnd()
method just before calling visitEnd() on the chained visitor.
That will cover items #2 and #3 from the list above. Notice that the class name
saved in the visit() method is used instead of a hard-coded constant,
which makes the transformation more generic.

The rest of the changes belong to method bytecode, so it's necessary
to overwrite the visitMethod() method.
There are two cases have to be covered:

Add instructions to call notify() method to all non-static methods.

Add initialization code to all <init> methods.

In the first case, new instructions are always added to the beginning of the method bytecode,
so chained CodeVisitor can be fired directly.
However, in case of the <init> method, instructions should be added
to the end of method, so they have to be inserted before visitInsn(RETURN),
meaning a custom CodeVisitor is required here. This is how
visitMethod() will look:

Similar to ClassAdapter, we can extend the CodeAdapter class
and overwrite only those methods that should change the stream of processing events.
In this case, we change the visitInsn() method to
verify if it is an event for the RETURN command and, if so, insert
required commands before delegating the event to the next CodeVisitor
in the chain.

That is basically it. The only piece we have left is the unit test for the whole
transformation.

Testing

First of all, we need to ensure that transformed class is functioning
properly after transformation, and that the injected code actually works.
These two test cases are represented by the testCounter() and
testNotifier() methods below.

The testCounter() method is a typical test case
that should ensure that code is functioning as expected.
The testNotifier() tests new functionality
added by the transformer. In both cases, all initialization is done in
the following setUp() method.

The transformed class is loaded in the loadClass()
method and a new instance is created. The same instance
is cast to the Notifier interface in order
to register TestListener, which records
notifications and enables retrieving them with the getEvents()
method, which is used in testNotifier().

The loadClass() method uses a custom ClassLoader,
which transforms classes on the fly using ASM with NotifierClassVisitor.

The code above assumes that a default constructor exists.
The complete source code is available in the Resources
section below.

Conclusion

As shown above, ASM allows us to write very compact code for generating new classes
and transforming existing bytecode. Using the described approach and
ASMifierClassVisitor, it is easy to implement quite advanced transformations.
In some cases, it could make sense to use CGLIB
which provides code transformation templates and a more high-level API on top of ASM,
but a lack of documentation and tutorials make it difficult to learn.