001: /***
002: * ASM: a very small and fast Java bytecode manipulation framework
003: * Copyright (c) 2000-2005 INRIA, France Telecom
004: * All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: * 1. Redistributions of source code must retain the above copyright
010: * notice, this list of conditions and the following disclaimer.
011: * 2. Redistributions in binary form must reproduce the above copyright
012: * notice, this list of conditions and the following disclaimer in the
013: * documentation and/or other materials provided with the distribution.
014: * 3. Neither the name of the copyright holders nor the names of its
015: * contributors may be used to endorse or promote products derived from
016: * this software without specific prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
021: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
022: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
023: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
024: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
025: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
026: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
027: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
028: * THE POSSIBILITY OF SUCH DAMAGE.
029: */package net.sf.retrotranslator.runtime.asm;
030:
031: /**
032: * A visitor to visit a Java method. The methods of this interface must be
033: * called in the following order: [ <tt>visitAnnotationDefault</tt> ] (
034: * <tt>visitAnnotation</tt> | <tt>visitParameterAnnotation</tt> |
035: * <tt>visitAttribute</tt> )* [ <tt>visitCode</tt> ( <tt>visit</tt><i>X</i>Insn</tt> |
036: * <tt>visitLabel</tt> | <tt>visitTryCatchBlock</tt> | <tt>visitLocalVariable</tt> |
037: * <tt>visitLineNumber</tt>)* <tt>visitMaxs</tt> ] <tt>visitEnd</tt>. In
038: * addition, the <tt>visit</tt><i>X</i>Insn</tt> and <tt>visitLabel</tt>
039: * methods must be called in the sequential order of the bytecode instructions
040: * of the visited code, and the <tt>visitLocalVariable</tt> and <tt>visitLineNumber</tt>
041: * methods must be called <i>after</i> the labels passed as arguments have been
042: * visited.
043: *
044: * @author Eric Bruneton
045: */
046: public interface MethodVisitor {
047:
048: // -------------------------------------------------------------------------
049: // Annotations and non standard attributes
050: // -------------------------------------------------------------------------
051:
052: /**
053: * Visits the default value of this annotation interface method.
054: *
055: * @return a non null visitor to the visit the actual default value of this
056: * annotation interface method. The 'name' parameters passed to the
057: * methods of this annotation visitor are ignored. Moreover, exacly
058: * one visit method must be called on this annotation visitor,
059: * followed by visitEnd.
060: */
061: AnnotationVisitor visitAnnotationDefault();
062:
063: /**
064: * Visits an annotation of this method.
065: *
066: * @param desc the class descriptor of the annotation class.
067: * @param visible <tt>true</tt> if the annotation is visible at runtime.
068: * @return a non null visitor to visit the annotation values.
069: */
070: AnnotationVisitor visitAnnotation(String desc, boolean visible);
071:
072: /**
073: * Visits an annotation of a parameter this method.
074: *
075: * @param parameter the parameter index.
076: * @param desc the class descriptor of the annotation class.
077: * @param visible <tt>true</tt> if the annotation is visible at runtime.
078: * @return a non null visitor to visit the annotation values.
079: */
080: AnnotationVisitor visitParameterAnnotation(int parameter,
081: String desc, boolean visible);
082:
083: /**
084: * Visits a non standard attribute of this method.
085: *
086: * @param attr an attribute.
087: */
088: void visitAttribute(Attribute attr);
089:
090: /**
091: * Starts the visit of the method's code, if any (i.e. non abstract method).
092: */
093: void visitCode();
094:
095: // -------------------------------------------------------------------------
096: // Normal instructions
097: // -------------------------------------------------------------------------
098:
099: /**
100: * Visits a zero operand instruction.
101: *
102: * @param opcode the opcode of the instruction to be visited. This opcode is
103: * either NOP, ACONST_NULL, ICONST_M1, ICONST_0, ICONST_1, ICONST_2,
104: * ICONST_3, ICONST_4, ICONST_5, LCONST_0, LCONST_1, FCONST_0,
105: * FCONST_1, FCONST_2, DCONST_0, DCONST_1, IALOAD, LALOAD, FALOAD,
106: * DALOAD, AALOAD, BALOAD, CALOAD, SALOAD, IASTORE, LASTORE, FASTORE,
107: * DASTORE, AASTORE, BASTORE, CASTORE, SASTORE, POP, POP2, DUP,
108: * DUP_X1, DUP_X2, DUP2, DUP2_X1, DUP2_X2, SWAP, IADD, LADD, FADD,
109: * DADD, ISUB, LSUB, FSUB, DSUB, IMUL, LMUL, FMUL, DMUL, IDIV, LDIV,
110: * FDIV, DDIV, IREM, LREM, FREM, DREM, INEG, LNEG, FNEG, DNEG, ISHL,
111: * LSHL, ISHR, LSHR, IUSHR, LUSHR, IAND, LAND, IOR, LOR, IXOR, LXOR,
112: * I2L, I2F, I2D, L2I, L2F, L2D, F2I, F2L, F2D, D2I, D2L, D2F, I2B,
113: * I2C, I2S, LCMP, FCMPL, FCMPG, DCMPL, DCMPG, IRETURN, LRETURN,
114: * FRETURN, DRETURN, ARETURN, RETURN, ARRAYLENGTH, ATHROW,
115: * MONITORENTER, or MONITOREXIT.
116: */
117: void visitInsn(int opcode);
118:
119: /**
120: * Visits an instruction with a single int operand.
121: *
122: * @param opcode the opcode of the instruction to be visited. This opcode is
123: * either BIPUSH, SIPUSH or NEWARRAY.
124: * @param operand the operand of the instruction to be visited.<br>
125: * When opcode is BIPUSH, operand value should be between
126: * Byte.MIN_VALUE and Byte.MAX_VALUE.<br>
127: * When opcode is SIPUSH, operand value should be between
128: * Short.MIN_VALUE and Short.MAX_VALUE.<br>
129: * When opcode is NEWARRAY, operand value should be one of
130: * {@link Opcodes#T_BOOLEAN}, {@link Opcodes#T_CHAR},
131: * {@link Opcodes#T_FLOAT}, {@link Opcodes#T_DOUBLE},
132: * {@link Opcodes#T_BYTE}, {@link Opcodes#T_SHORT},
133: * {@link Opcodes#T_INT} or {@link Opcodes#T_LONG}.
134: */
135: void visitIntInsn(int opcode, int operand);
136:
137: /**
138: * Visits a local variable instruction. A local variable instruction is an
139: * instruction that loads or stores the value of a local variable.
140: *
141: * @param opcode the opcode of the local variable instruction to be visited.
142: * This opcode is either ILOAD, LLOAD, FLOAD, DLOAD, ALOAD, ISTORE,
143: * LSTORE, FSTORE, DSTORE, ASTORE or RET.
144: * @param var the operand of the instruction to be visited. This operand is
145: * the index of a local variable.
146: */
147: void visitVarInsn(int opcode, int var);
148:
149: /**
150: * Visits a type instruction. A type instruction is an instruction that
151: * takes a type descriptor as parameter.
152: *
153: * @param opcode the opcode of the type instruction to be visited. This
154: * opcode is either NEW, ANEWARRAY, CHECKCAST or INSTANCEOF.
155: * @param desc the operand of the instruction to be visited. This operand is
156: * must be a fully qualified class name in internal form, or the type
157: * descriptor of an array type (see {@link Type Type}).
158: */
159: void visitTypeInsn(int opcode, String desc);
160:
161: /**
162: * Visits a field instruction. A field instruction is an instruction that
163: * loads or stores the value of a field of an object.
164: *
165: * @param opcode the opcode of the type instruction to be visited. This
166: * opcode is either GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.
167: * @param owner the internal name of the field's owner class (see {@link
168: * Type#getInternalName() getInternalName}).
169: * @param name the field's name.
170: * @param desc the field's descriptor (see {@link Type Type}).
171: */
172: void visitFieldInsn(int opcode, String owner, String name,
173: String desc);
174:
175: /**
176: * Visits a method instruction. A method instruction is an instruction that
177: * invokes a method.
178: *
179: * @param opcode the opcode of the type instruction to be visited. This
180: * opcode is either INVOKEVIRTUAL, INVOKESPECIAL, INVOKESTATIC or
181: * INVOKEINTERFACE.
182: * @param owner the internal name of the method's owner class (see {@link
183: * Type#getInternalName() getInternalName}).
184: * @param name the method's name.
185: * @param desc the method's descriptor (see {@link Type Type}).
186: */
187: void visitMethodInsn(int opcode, String owner, String name,
188: String desc);
189:
190: /**
191: * Visits a jump instruction. A jump instruction is an instruction that may
192: * jump to another instruction.
193: *
194: * @param opcode the opcode of the type instruction to be visited. This
195: * opcode is either IFEQ, IFNE, IFLT, IFGE, IFGT, IFLE, IF_ICMPEQ,
196: * IF_ICMPNE, IF_ICMPLT, IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ACMPEQ,
197: * IF_ACMPNE, GOTO, JSR, IFNULL or IFNONNULL.
198: * @param label the operand of the instruction to be visited. This operand
199: * is a label that designates the instruction to which the jump
200: * instruction may jump.
201: */
202: void visitJumpInsn(int opcode, Label label);
203:
204: /**
205: * Visits a label. A label designates the instruction that will be visited
206: * just after it.
207: *
208: * @param label a {@link Label Label} object.
209: */
210: void visitLabel(Label label);
211:
212: // -------------------------------------------------------------------------
213: // Special instructions
214: // -------------------------------------------------------------------------
215:
216: /**
217: * Visits a LDC instruction.
218: *
219: * @param cst the constant to be loaded on the stack. This parameter must be
220: * a non null {@link Integer}, a {@link Float}, a {@link Long}, a
221: * {@link Double} a {@link String} (or a {@link Type} for
222: * <tt>.class</tt> constants, for classes whose version is 49.0 or
223: * more).
224: */
225: void visitLdcInsn(Object cst);
226:
227: /**
228: * Visits an IINC instruction.
229: *
230: * @param var index of the local variable to be incremented.
231: * @param increment amount to increment the local variable by.
232: */
233: void visitIincInsn(int var, int increment);
234:
235: /**
236: * Visits a TABLESWITCH instruction.
237: *
238: * @param min the minimum key value.
239: * @param max the maximum key value.
240: * @param dflt beginning of the default handler block.
241: * @param labels beginnings of the handler blocks. <tt>labels[i]</tt> is
242: * the beginning of the handler block for the <tt>min + i</tt> key.
243: */
244: void visitTableSwitchInsn(int min, int max, Label dflt,
245: Label labels[]);
246:
247: /**
248: * Visits a LOOKUPSWITCH instruction.
249: *
250: * @param dflt beginning of the default handler block.
251: * @param keys the values of the keys.
252: * @param labels beginnings of the handler blocks. <tt>labels[i]</tt> is
253: * the beginning of the handler block for the <tt>keys[i]</tt> key.
254: */
255: void visitLookupSwitchInsn(Label dflt, int keys[], Label labels[]);
256:
257: /**
258: * Visits a MULTIANEWARRAY instruction.
259: *
260: * @param desc an array type descriptor (see {@link Type Type}).
261: * @param dims number of dimensions of the array to allocate.
262: */
263: void visitMultiANewArrayInsn(String desc, int dims);
264:
265: // -------------------------------------------------------------------------
266: // Exceptions table entries, debug information,
267: // max stack size and max locals
268: // -------------------------------------------------------------------------
269:
270: /**
271: * Visits a try catch block.
272: *
273: * @param start beginning of the exception handler's scope (inclusive).
274: * @param end end of the exception handler's scope (exclusive).
275: * @param handler beginning of the exception handler's code.
276: * @param type internal name of the type of exceptions handled by the
277: * handler, or <tt>null</tt> to catch any exceptions (for "finally"
278: * blocks).
279: */
280: void visitTryCatchBlock(Label start, Label end, Label handler,
281: String type);
282:
283: /**
284: * Visits a local variable declaration.
285: *
286: * @param name the name of a local variable.
287: * @param desc the type descriptor of this local variable.
288: * @param signature the type signature of this local variable. May be
289: * <tt>null</tt> if the local variable type does not use generic
290: * types.
291: * @param start the first instruction corresponding to the scope of this
292: * local variable (inclusive).
293: * @param end the last instruction corresponding to the scope of this local
294: * variable (exclusive).
295: * @param index the local variable's index.
296: * @throws IllegalArgumentException if one of the labels has not already
297: * been visited by this visitor (by the
298: * {@link #visitLabel visitLabel} method).
299: */
300: void visitLocalVariable(String name, String desc, String signature,
301: Label start, Label end, int index);
302:
303: /**
304: * Visits a line number declaration.
305: *
306: * @param line a line number. This number refers to the source file from
307: * which the class was compiled.
308: * @param start the first instruction corresponding to this line number.
309: * @throws IllegalArgumentException if <tt>start</tt> has not already been
310: * visited by this visitor (by the {@link #visitLabel visitLabel}
311: * method).
312: */
313: void visitLineNumber(int line, Label start);
314:
315: /**
316: * Visits the maximum stack size and the maximum number of local variables
317: * of the method.
318: *
319: * @param maxStack maximum stack size of the method.
320: * @param maxLocals maximum number of local variables for the method.
321: */
322: void visitMaxs(int maxStack, int maxLocals);
323:
324: /**
325: * Visits the end of the method. This method, which is the last one to be
326: * called, is used to inform the visitor that all the annotations and
327: * attributes of the method have been visited.
328: */
329: void visitEnd();
330: }
|