ASM 9.6 · org.objectweb.asm.tree

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 ClassVisitor 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 classReader = new ClassReader(source);
  ClassNode classNode = new ClassNode();
  classReader.accept(classNode, 0);

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

  ClassWriter classWriter = new ClassWriter(0);
  classNode.accept(classWriter);

Using a simple ClassVisitor 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 classReader = new ClassReader(source);
  ClassWriter classWriter = new ClassWriter(0);
  ClassVisitor classVisitor = new ClassVisitor(ASM7, classWriter) {
    public MethodVisitor visitMethod(int access, String name,
        String desc, String signature, String[] exceptions) {
      final MethodVisitor methodVisitor = 
          super.visitMethod(access, name, desc, signature, exceptions);
      MethodNode methodNode = new MethodNode(access, name, desc, signature, exceptions) {
        public void visitEnd() {
          // transform or analyze method code using tree API
          accept(methodVisitor);
        }
      };
    }
  };
  classReader.accept(classVisitor, 0);

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 methodNode = new MethodNode(...);
methodNode.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 methods:

MethodNode methodNode = new MethodNode(...);
methodNode.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 a saved pointer.

MethodNode methodNode = new MethodNode(...);
methodNode.visitVarInsn(ALOAD, 0);
AbstractInsnNode ptr = methodNode.instructions.getLast();
methodNode.visitVarInsn(ALOAD, 1);
// inserts an instruction between ALOAD 0 and ALOAD 1
methodNode.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 = methodNode.instructions.iterator();
while (it.hasNext()) {
    AbstractInsnNode insnNode = (AbstractInsnNode) it.next();
    if (...) {
        it.add(new VarInsnNode(ALOAD, 0));
    }
}

It is also possible to convert an instruction list into an array and iterate through array elements:

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

If you want to insert these instructions through the MethodVisitor methods, 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 = methodNode.instructions.toArray();
for(int i = 0; i<insns.length; i++) {
    AbstractInsnNode insn = insns[i];
    if (...) {
        MethodNode toInsert = new MethodNode();
        toInsert.visitVarInsn(ALOAD, 0);
        toInsert.visitVarInsn(ALOAD, 1);
        m.instructions.insert(insn, toInsert.instructions);
    }
}

Class Summary

Modifier and Type	Class and Description
public abstract class	AbstractInsnNode A node that represents a bytecode instruction.
public class	AnnotationNode A node that represents an annotation.
public class	ClassNode A node that represents a class.
public class	FieldInsnNode A node that represents a field instruction.
public class	FieldNode A node that represents a field.
public class	FrameNode A node that represents a stack map frame.
public class	IincInsnNode A node that represents an IINC instruction.
public class	InnerClassNode A node that represents an inner class.
public class	InsnList A doubly linked list of `AbstractInsnNode` objects.
public class	InsnNode A node that represents a zero operand instruction.
public class	IntInsnNode A node that represents an instruction with a single int operand.
public class	InvokeDynamicInsnNode A node that represents an invokedynamic instruction.
public class	JumpInsnNode A node that represents a jump instruction.
public class	LabelNode An `AbstractInsnNode` that encapsulates a `Label`.
public class	LdcInsnNode A node that represents an LDC instruction.
public class	LineNumberNode A node that represents a line number declaration.
public class	LocalVariableAnnotationNode A node that represents a type annotation on a local or resource variable.
public class	LocalVariableNode A node that represents a local variable declaration.
public class	LookupSwitchInsnNode A node that represents a LOOKUPSWITCH instruction.
public class	MethodInsnNode A node that represents a method instruction.
public class	MethodNode A node that represents a method.
public class	ModuleExportNode A node that represents an exported package with its name and the module that can access to it.
public class	ModuleNode A node that represents a module declaration.
public class	ModuleOpenNode A node that represents an opened package with its name and the module that can access it.
public class	ModuleProvideNode A node that represents a service and its implementation provided by the current module.
public class	ModuleRequireNode A node that represents a required module with its name and access of a module descriptor.
public class	MultiANewArrayInsnNode A node that represents a MULTIANEWARRAY instruction.
public class	ParameterNode A node that represents a parameter of a method.
public class	RecordComponentNode A node that represents a record component.
public class	TableSwitchInsnNode A node that represents a TABLESWITCH instruction.
public class	TryCatchBlockNode A node that represents a try catch block.
public class	TypeAnnotationNode A node that represents a type annotation.
public class	TypeInsnNode A node that represents a type instruction.
public class	UnsupportedClassVersionException Exception thrown in `AnnotationNode#check`, `ClassNode#check`, `FieldNode#check` and `MethodNode#check` when these nodes (or their children, recursively) contain elements that were introduced in more recent versions of the ASM API than version passed to these methods.
pack-priv class	Util Utility methods to convert an array of primitive or object values to a mutable ArrayList, not baked by the array (unlike `java.util.Arrays#asList`).
public class	VarInsnNode A node that represents a local variable instruction.

Package org.objectweb.asm.tree

Class Summary