KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > tc > asm > MethodVisitor


1 /***
2  * ASM: a very small and fast Java bytecode manipulation framework
3  * Copyright (c) 2000-2005 INRIA, France Telecom
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the copyright holders nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
28  * THE POSSIBILITY OF SUCH DAMAGE.
29  */

30 package com.tc.asm;
31
32 /**
33  * A visitor to visit a Java method. The methods of this interface must be
34  * called in the following order: [ <tt>visitAnnotationDefault</tt> ] (
35  * <tt>visitAnnotation</tt> | <tt>visitParameterAnnotation</tt> |
36  * <tt>visitAttribute</tt> )* [ <tt>visitCode</tt> ( <tt>visit</tt><i>X</i>Insn</tt> |
37  * <tt>visitLabel</tt> | <tt>visitTryCatchBlock</tt> | <tt>visitLocalVariable</tt> |
38  * <tt>visitLineNumber</tt>)* <tt>visitMaxs</tt> ] <tt>visitEnd</tt>. In
39  * addition, the <tt>visit</tt><i>X</i>Insn</tt> and <tt>visitLabel</tt>
40  * methods must be called in the sequential order of the bytecode instructions
41  * of the visited code, and the <tt>visitLocalVariable</tt> and <tt>visitLineNumber</tt>
42  * methods must be called <i>after</i> the labels passed as arguments have been
43  * visited.
44  *
45  * @author Eric Bruneton
46  */

47 public interface MethodVisitor {
48
49     // -------------------------------------------------------------------------
50
// Annotations and non standard attributes
51
// -------------------------------------------------------------------------
52

53     /**
54      * Visits the default value of this annotation interface method.
55      *
56      * @return a non null visitor to the visit the actual default value of this
57      * annotation interface method. The 'name' parameters passed to the
58      * methods of this annotation visitor are ignored. Moreover, exacly
59      * one visit method must be called on this annotation visitor,
60      * followed by visitEnd.
61      */

62     AnnotationVisitor visitAnnotationDefault();
63
64     /**
65      * Visits an annotation of this method.
66      *
67      * @param desc the class descriptor of the annotation class.
68      * @param visible <tt>true</tt> if the annotation is visible at runtime.
69      * @return a non null visitor to visit the annotation values.
70      */

71     AnnotationVisitor visitAnnotation(String JavaDoc desc, boolean visible);
72
73     /**
74      * Visits an annotation of a parameter this method.
75      *
76      * @param parameter the parameter index.
77      * @param desc the class descriptor of the annotation class.
78      * @param visible <tt>true</tt> if the annotation is visible at runtime.
79      * @return a non null visitor to visit the annotation values.
80      */

81     AnnotationVisitor visitParameterAnnotation(
82         int parameter,
83         String JavaDoc desc,
84         boolean visible);
85
86     /**
87      * Visits a non standard attribute of this method.
88      *
89      * @param attr an attribute.
90      */

91     void visitAttribute(Attribute attr);
92
93     /**
94      * Starts the visit of the method's code, if any (i.e. non abstract method).
95      */

96     void visitCode();
97
98     // -------------------------------------------------------------------------
99
// Normal instructions
100
// -------------------------------------------------------------------------
101

102     /**
103      * Visits a zero operand instruction.
104      *
105      * @param opcode the opcode of the instruction to be visited. This opcode is
106      * either NOP, ACONST_NULL, ICONST_M1, ICONST_0, ICONST_1, ICONST_2,
107      * ICONST_3, ICONST_4, ICONST_5, LCONST_0, LCONST_1, FCONST_0,
108      * FCONST_1, FCONST_2, DCONST_0, DCONST_1, IALOAD, LALOAD, FALOAD,
109      * DALOAD, AALOAD, BALOAD, CALOAD, SALOAD, IASTORE, LASTORE, FASTORE,
110      * DASTORE, AASTORE, BASTORE, CASTORE, SASTORE, POP, POP2, DUP,
111      * DUP_X1, DUP_X2, DUP2, DUP2_X1, DUP2_X2, SWAP, IADD, LADD, FADD,
112      * DADD, ISUB, LSUB, FSUB, DSUB, IMUL, LMUL, FMUL, DMUL, IDIV, LDIV,
113      * FDIV, DDIV, IREM, LREM, FREM, DREM, INEG, LNEG, FNEG, DNEG, ISHL,
114      * LSHL, ISHR, LSHR, IUSHR, LUSHR, IAND, LAND, IOR, LOR, IXOR, LXOR,
115      * I2L, I2F, I2D, L2I, L2F, L2D, F2I, F2L, F2D, D2I, D2L, D2F, I2B,
116      * I2C, I2S, LCMP, FCMPL, FCMPG, DCMPL, DCMPG, IRETURN, LRETURN,
117      * FRETURN, DRETURN, ARETURN, RETURN, ARRAYLENGTH, ATHROW,
118      * MONITORENTER, or MONITOREXIT.
119      */

120     void visitInsn(int opcode);
121
122     /**
123      * Visits an instruction with a single int operand.
124      *
125      * @param opcode the opcode of the instruction to be visited. This opcode is
126      * either BIPUSH, SIPUSH or NEWARRAY.
127      * @param operand the operand of the instruction to be visited.<br>
128      * When opcode is BIPUSH, operand value should be between
129      * Byte.MIN_VALUE and Byte.MAX_VALUE.<br>
130      * When opcode is SIPUSH, operand value should be between
131      * Short.MIN_VALUE and Short.MAX_VALUE.<br>
132      * When opcode is NEWARRAY, operand value should be one of
133      * {@link Opcodes#T_BOOLEAN}, {@link Opcodes#T_CHAR},
134      * {@link Opcodes#T_FLOAT}, {@link Opcodes#T_DOUBLE},
135      * {@link Opcodes#T_BYTE}, {@link Opcodes#T_SHORT},
136      * {@link Opcodes#T_INT} or {@link Opcodes#T_LONG}.
137      */

138     void visitIntInsn(int opcode, int operand);
139
140     /**
141      * Visits a local variable instruction. A local variable instruction is an
142      * instruction that loads or stores the value of a local variable.
143      *
144      * @param opcode the opcode of the local variable instruction to be visited.
145      * This opcode is either ILOAD, LLOAD, FLOAD, DLOAD, ALOAD, ISTORE,
146      * LSTORE, FSTORE, DSTORE, ASTORE or RET.
147      * @param var the operand of the instruction to be visited. This operand is
148      * the index of a local variable.
149      */

150     void visitVarInsn(int opcode, int var);
151
152     /**
153      * Visits a type instruction. A type instruction is an instruction that
154      * takes a type descriptor as parameter.
155      *
156      * @param opcode the opcode of the type instruction to be visited. This
157      * opcode is either NEW, ANEWARRAY, CHECKCAST or INSTANCEOF.
158      * @param desc the operand of the instruction to be visited. This operand is
159      * must be a fully qualified class name in internal form, or the type
160      * descriptor of an array type (see {@link Type Type}).
161      */

162     void visitTypeInsn(int opcode, String JavaDoc desc);
163
164     /**
165      * Visits a field instruction. A field instruction is an instruction that
166      * loads or stores the value of a field of an object.
167      *
168      * @param opcode the opcode of the type instruction to be visited. This
169      * opcode is either GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD.
170      * @param owner the internal name of the field's owner class (see {@link
171      * Type#getInternalName() getInternalName}).
172      * @param name the field's name.
173      * @param desc the field's descriptor (see {@link Type Type}).
174      */

175     void visitFieldInsn(int opcode, String JavaDoc owner, String JavaDoc name, String JavaDoc desc);
176
177     /**
178      * Visits a method instruction. A method instruction is an instruction that
179      * invokes a method.
180      *
181      * @param opcode the opcode of the type instruction to be visited. This
182      * opcode is either INVOKEVIRTUAL, INVOKESPECIAL, INVOKESTATIC or
183      * INVOKEINTERFACE.
184      * @param owner the internal name of the method's owner class (see {@link
185      * Type#getInternalName() getInternalName}).
186      * @param name the method's name.
187      * @param desc the method's descriptor (see {@link Type Type}).
188      */

189     void visitMethodInsn(int opcode, String JavaDoc owner, String JavaDoc name, String JavaDoc desc);
190
191     /**
192      * Visits a jump instruction. A jump instruction is an instruction that may
193      * jump to another instruction.
194      *
195      * @param opcode the opcode of the type instruction to be visited. This
196      * opcode is either IFEQ, IFNE, IFLT, IFGE, IFGT, IFLE, IF_ICMPEQ,
197      * IF_ICMPNE, IF_ICMPLT, IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ACMPEQ,
198      * IF_ACMPNE, GOTO, JSR, IFNULL or IFNONNULL.
199      * @param label the operand of the instruction to be visited. This operand
200      * is a label that designates the instruction to which the jump
201      * instruction may jump.
202      */

203     void visitJumpInsn(int opcode, Label label);
204
205     /**
206      * Visits a label. A label designates the instruction that will be visited
207      * just after it.
208      *
209      * @param label a {@link Label Label} object.
210      */

211     void visitLabel(Label label);
212
213     // -------------------------------------------------------------------------
214
// Special instructions
215
// -------------------------------------------------------------------------
216

217     /**
218      * Visits a LDC instruction.
219      *
220      * @param cst the constant to be loaded on the stack. This parameter must be
221      * a non null {@link Integer}, a {@link Float}, a {@link Long}, a
222      * {@link Double} a {@link String} (or a {@link Type} for
223      * <tt>.class</tt> constants, for classes whose version is 49.0 or
224      * more).
225      */

226     void visitLdcInsn(Object JavaDoc cst);
227
228     /**
229      * Visits an IINC instruction.
230      *
231      * @param var index of the local variable to be incremented.
232      * @param increment amount to increment the local variable by.
233      */

234     void visitIincInsn(int var, int increment);
235
236     /**
237      * Visits a TABLESWITCH instruction.
238      *
239      * @param min the minimum key value.
240      * @param max the maximum key value.
241      * @param dflt beginning of the default handler block.
242      * @param labels beginnings of the handler blocks. <tt>labels[i]</tt> is
243      * the beginning of the handler block for the <tt>min + i</tt> key.
244      */

245     void visitTableSwitchInsn(int min, int max, Label dflt, 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 JavaDoc 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, String JavaDoc type);
281
282     /**
283      * Visits a local variable declaration.
284      *
285      * @param name the name of a local variable.
286      * @param desc the type descriptor of this local variable.
287      * @param signature the type signature of this local variable. May be
288      * <tt>null</tt> if the local variable type does not use generic
289      * types.
290      * @param start the first instruction corresponding to the scope of this
291      * local variable (inclusive).
292      * @param end the last instruction corresponding to the scope of this local
293      * variable (exclusive).
294      * @param index the local variable's index.
295      * @throws IllegalArgumentException if one of the labels has not already
296      * been visited by this visitor (by the
297      * {@link #visitLabel visitLabel} method).
298      */

299     void visitLocalVariable(
300         String JavaDoc name,
301         String JavaDoc desc,
302         String JavaDoc signature,
303         Label start,
304         Label end,
305         int index);
306
307     /**
308      * Visits a line number declaration.
309      *
310      * @param line a line number. This number refers to the source file from
311      * which the class was compiled.
312      * @param start the first instruction corresponding to this line number.
313      * @throws IllegalArgumentException if <tt>start</tt> has not already been
314      * visited by this visitor (by the {@link #visitLabel visitLabel}
315      * method).
316      */

317     void visitLineNumber(int line, Label start);
318
319     /**
320      * Visits the maximum stack size and the maximum number of local variables
321      * of the method.
322      *
323      * @param maxStack maximum stack size of the method.
324      * @param maxLocals maximum number of local variables for the method.
325      */

326     void visitMaxs(int maxStack, int maxLocals);
327
328     /**
329      * Visits the end of the method. This method, which is the last one to be
330      * called, is used to inform the visitor that all the annotations and
331      * attributes of the method have been visited.
332      */

333     void visitEnd();
334 }
335
Popular Tags