package.html revision 674060f01e9090cd21b3c5656cc3204912ad17a6
1<html> 2<!-- 3 * ASM: a very small and fast Java bytecode manipulation framework 4 * Copyright (c) 2000-2005 INRIA, France Telecom 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 3. Neither the name of the copyright holders nor the names of its 16 * contributors may be used to endorse or promote products derived from 17 * this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 29 * THE POSSIBILITY OF SUCH DAMAGE. 30--> 31<body> 32 33<p> 34Provides an ASM visitor that constructs a tree representation of the 35classes it visits. This class adapter can be useful to implement "complex" 36class manipulation operations, i.e., operations that would be very hard to 37implement without using a tree representation (such as optimizing the number 38of local variables used by a method). 39</p> 40 41<p> 42However, this class adapter has a cost: it makes ASM bigger and slower. Indeed 43it requires more than twenty new classes, and multiplies the time needed to 44transform a class by almost two (it is almost two times faster to read, "modify" 45and write a class with a ClassAdapter than with a ClassNode). This is why 46this package is bundled in an optional <tt>asm-tree.jar</tt> library that 47is separated from (but requires) the <tt>asm.jar</tt> library, which contains 48the core ASM framework. This is also why <i><font color="red">it is recommended 49not to use this class adapter when it is possible</font></i>. 50</p> 51 52<p> 53The root class is the ClassNode, that can be created from existing bytecode. For example: 54</p> 55 56<pre> 57 ClassReader cr = new ClassReader(source); 58 ClassNode cn = new ClassNode(); 59 cr.accept(cn, true); 60</pre> 61 62<p> 63Now content of ClassNode can be modified and then 64serialized back into bytecode: 65</p> 66 67<pre> 68 ClassWriter cw = new ClassWriter(true); 69 cn.accept(cw); 70</pre> 71 72<p> 73Using simple ClassAdapter it is possible to create MethodNode instances per-method. 74In this example MethodNode is acting as a buffer that is flushed out at visitEnd() call: 75</p> 76 77<pre> 78 ClassReader cr = new ClassReader(source); 79 ClassWriter cw = new ClassWriter(); 80 ClassAdapter ca = new ClassAdapter(cw) { 81 public MethodVisitor visitMethod(int access, String name, 82 String desc, String signature, String[] exceptions) { 83 final MethodVisitor mv = super.visitMethod(access, name, desc, signature, exceptions); 84 MethodNode mn = new MethodNode(access, name, desc, signature, exceptions) { 85 public void visitEnd() { 86 // transform or analyze method code using tree API 87 accept(mv); 88 } 89 }; 90 } 91 }; 92 cr.accept(ca, true); 93</pre> 94 95<p> 96Several strategies can be used to construct method code from scratch. The first 97option is to create a MethodNode, and then create XXXInsnNode instances and 98add them to the instructions list: 99</p> 100 101<pre> 102MethodNode m = new MethodNode(...); 103m.instructions.add(new VarInsnNode(ALOAD, 0)); 104... 105</pre> 106 107<p> 108Alternatively, you can use the fact that MethodNode is a MethodVisitor, and use 109that to create the XXXInsnNode and add them to the instructions list through 110the standard MethodVisitor interface: 111</p> 112 113<pre> 114MethodNode m = new MethodNode(...); 115m.visitVarInsn(ALOAD, 0); 116... 117</pre> 118 119<p> 120If you cannot generate all the instructions in sequential order, i.e. if you 121need to save some pointer in the instruction list and then insert instructions 122at that place after other instructions have been generated, you can use InsnList 123methods insert() and insertBefore() to insert instructions at saved pointer. 124</p> 125 126<pre> 127MethodNode m = new MethodNode(...); 128m.visitVarInsn(ALOAD, 0); 129AbstractInsnNode ptr = m.instructions.getLast(); 130m.visitVarInsn(ALOAD, 1); 131// inserts an instruction between ALOAD 0 and ALOAD 1 132m.instructions.insert(ptr, new VarInsnNode(ALOAD, 0)); 133... 134</pre> 135 136<p> 137If you need to insert instructions while iterating over an existing instruction 138list, you can also use several strategies. The first one is to use a 139ListIterator over the instruction list: 140</p> 141 142<pre> 143ListIterator it = m.instructions.iterator(); 144while (it.hasNext()) { 145 AbstractInsnNode n = (AbstractInsnNode) it.next(); 146 if (...) { 147 it.add(new VarInsnNode(ALOAD, 0)); 148 } 149} 150</pre> 151 152<p> 153It is also possible to convert instruction list into the array and iterate trough 154array elements: 155</p> 156 157<pre> 158AbstractInsnNode[] insns = m.instructions.toArray(); 159for(int i = 0; i<insns.length; i++) { 160 AbstractInsnNode n = insns[i]; 161 if (...) { 162 m.instructions.insert(n, new VarInsnNode(ALOAD, 0)); 163 } 164} 165</pre> 166 167<p> 168If you want to insert these instructions through the MethodVisitor interface, 169you can use another instance of MethodNode as a MethodVisitor and then 170insert instructions collected by that instance into the instruction list. 171For example: 172</p> 173 174<pre> 175AbstractInsnNode[] insns = m.instructions.toArray(); 176for(int i = 0; i<insns.length; i++) { 177 AbstractInsnNode n = insns[i]; 178 if (...) { 179 MethodNode mn = new MethodNode(); 180 mn.visitVarInsn(ALOAD, 0); 181 mn.visitVarInsn(ALOAD, 1); 182 m.instructions.insert(n, mn.instructions); 183 } 184} 185</pre> 186 187<p> 188@since ASM 1.3.3 189</p> 190 191</body> 192</html> 193