Terracotta

The ASM framework is organized around the {@link org.objectweb.asm.ClassVisitor ClassVisitor}, {@link org.objectweb.asm.FieldVisitor FieldVisitor} and {@link org.objectweb.asm.MethodVisitor MethodVisitor} interfaces, which allow one to visit the fields and methods of a class, including the bytecode instructions of each method.

In addition to these main interfaces, ASM provides a {@link org.objectweb.asm.ClassReader ClassReader} class, that can parse an existing class and make a given visitor visit it. ASM also provides a {@link org.objectweb.asm.ClassWriter ClassWriter} class, which is a visitor that generates Java class files.

In order to generate a class from scratch, only the {@link org.objectweb.asm.ClassWriter ClassWriter} class is necessary. Indeed, in order to generate a class, one must just call its visitXXX methods with the appropriate arguments to generate the desired fields and methods. See the "helloworld" example in the ASM distribution for more details about class generation.

In order to modify existing classes, one must use a {@link org.objectweb.asm.ClassReader ClassReader} class to analyze the original class, a class modifier, and a {@link org.objectweb.asm.ClassWriter ClassWriter} to construct the modified class. The class modifier is just a {@link org.objectweb.asm.ClassVisitor ClassVisitor} that delegates most of the work to another {@link org.objectweb.asm.ClassVisitor ClassVisitor}, but that sometimes changes some parameter values, or call additional methods, in order to implement the desired modification process. In order to make it easier to implement such class modifiers, ASM provides the {@link org.objectweb.asm.ClassAdapter ClassAdapter} and {@link org.objectweb.asm.MethodAdapter MethodAdapter} classes, which implement the {@link org.objectweb.asm.ClassVisitor ClassVisitor} and {@link org.objectweb.asm.MethodVisitor MethodVisitor} interfaces by delegating all work to other visitors. See the "adapt" example in the ASM distribution for more details about class modification.

The size of the core ASM library, asm.jar, is only 42KB, which is much smaller than the size of the BCEL library (504KB), and than the size of the SERP library (150KB). ASM is also much faster than these tools. Indeed the overhead of a load time class transformation process is of the order of 60% with ASM, 700% or more with BCEL, and 1100% or more with SERP (see the test/perf directory in the ASM distribution)! @since ASM 1.3

Provides an ASM visitor that constructs a tree representation of the classes it visits. This class adapter can be useful to implement "complex" class manipulation operations, i.e., operations that would be very hard to implement without using a tree representation (such as optimizing the number of local variables used by a method).

However, this class adapter has a cost: it makes ASM bigger and slower. Indeed it requires more than twenty new classes, and multiplies the time needed to transform a class by almost two (it is almost two times faster to read, "modify" and write a class with a ClassAdapter than with a ClassNode). This is why this package is bundled in an optional asm-tree.jar library that is separated from (but requires) the asm.jar library, which contains the core ASM framework. This is also why it is recommended not to use this class adapter when it is possible.

The root class is the ClassNode, that can be created from existing bytecode. For example:

  ClassReader cr = new ClassReader(source);
  ClassNode cn = new ClassNode();
  cr.accept(cn, true);

Now content of ClassNode can be modified and then serialized back into bytecode:

  ClassWriter cw = new ClassWriter(true);
  cn.accept(cw);

Using simple ClassAdapter it is possible to create MethodNode instances per-method. In this example MethodNode is acting as a buffer that is flushed out at visitEnd() call:

  ClassReader cr = new ClassReader(source);
  ClassWriter cw = new ClassWriter();
  ClassAdapter ca = new ClassAdapter(cw) {
      public MethodVisitor visitMethod(int access, String name, 
          String desc, String signature, String[] exceptions) {
        final MethodVisitor mv = super.visitMethod(access, name, desc, signature, exceptions);
        MethodNode mn = new MethodNode(access, name, desc, signature, exceptions) {
            public void visitEnd() {
              // transform or analyze method code using tree API
              accept(mv);
            }
          };
      }
    };
  cr.accept(ca, true);

Several strategies can be used to construct method code from scratch. The first option is to create a MethodNode, and then create XXXInsnNode instances and add them to the instructions list:

MethodNode m = new MethodNode(...);
m.instructions.add(new VarInsnNode(ALOAD, 0));
...

Alternatively, you can use the fact that MethodNode is a MethodVisitor, and use that to create the XXXInsnNode and add them to the instructions list through the standard MethodVisitor interface:

MethodNode m = new MethodNode(...);
m.visitVarInsn(ALOAD, 0);
...

If you cannot generate all the instructions in sequential order, i.e. if you need to save some pointer in the instruction list and then insert instructions at that place after other instructions have been generated, you can use InsnList methods insert() and insertBefore() to insert instructions at saved pointer.

MethodNode m = new MethodNode(...);
m.visitVarInsn(ALOAD, 0);
AbstractInsnNode ptr = m.instructions.getLast();
m.visitVarInsn(ALOAD, 1);
// inserts an instruction between ALOAD 0 and ALOAD 1
m.instructions.insert(ptr, new VarInsnNode(ALOAD, 0));
...

If you need to insert instructions while iterating over an existing instruction list, you can also use several strategies. The first one is to use a ListIterator over the instruction list:

ListIterator it = m.instructions.iterator();
while (it.hasNext()) {
    AbstractInsnNode n = (AbstractInsnNode) it.next();
    if (...) {
        it.add(new VarInsnNode(ALOAD, 0));
    }
}

It is also possible to convert instruction list into the array and iterate trough array elements:

AbstractInsnNode[] insns = m.instructions.toArray();
for(int i = 0; i<insns.length; i++) {
    AbstractInsnNode n = insns[i];
    if (...) {
        m.instructions.insert(n, new VarInsnNode(ALOAD, 0));
    }
}

If you want to insert these instructions through the MethodVisitor interface, you can use another instance of MethodNode as a MethodVisitor and then insert instructions collected by that instance into the instruction list. For example:

AbstractInsnNode[] insns = m.instructions.toArray();
for(int i = 0; i<insns.length; i++) {
    AbstractInsnNode n = insns[i];
    if (...) {
        MethodNode mn = new MethodNode();
        mn.visitVarInsn(ALOAD, 0);
        mn.visitVarInsn(ALOAD, 1);
        m.instructions.insert(n, mn.instructions);
    }
}

@since ASM 1.3.3

Provides a framework for static code analysis based on the asm.tree package.

Basic usage:

ClassReader cr = new ClassReader(bytecode);
ClassNode cn = new ClassNode();
cr.accept(cn, ClassReader.SKIP_DEBUG);

List methods = cn.methods;
for (int i = 0; i < methods.size(); ++i) {
    MethodNode method = (MethodNode) methods.get(i);
    if (method.instructions.size() > 0) {
        Analyzer a = new Analyzer(new BasicInterpreter());
        a.analyze(cn.name, method);
        Frame[] frames = a.getFrames();
        // Elements of the frames arrray now contains info for each instruction 
        // from the analyzed method. BasicInterpreter creates BasicValue, that
        // is using simplified type system that distinguishes the UNINITIALZED, 
        // INT, FLOAT, LONG, DOUBLE, REFERENCE and RETURNADDRESS types.
        ...
    }
}   

@since ASM 1.4.3