1 /*
2 * MIT License
3 * Copyright (c) 2006-2025 JMockit developers
4 * See LICENSE file for full license text.
5 */
6 package mockit.asm.methods;
7
8 import edu.umd.cs.findbugs.annotations.NonNull;
9 import edu.umd.cs.findbugs.annotations.Nullable;
10
11 import mockit.asm.BaseWriter;
12 import mockit.asm.annotations.AnnotationVisitor;
13 import mockit.asm.constantPool.ConstantPoolGeneration;
14 import mockit.asm.controlFlow.Label;
15 import mockit.asm.jvmConstants.ArrayElementType;
16 import mockit.asm.jvmConstants.Opcodes;
17 import mockit.asm.types.ArrayType;
18 import mockit.asm.types.JavaType;
19 import mockit.asm.types.MethodType;
20 import mockit.asm.types.ObjectType;
21 import mockit.asm.util.MethodHandle;
22
23 import org.checkerframework.checker.index.qual.NonNegative;
24
25 /**
26 * A visitor to visit a Java method, in the following order:<br>
27 * ({@link #visitAnnotation})* ({@link #visitParameterAnnotation})* [(<code>visit<i>X</i>Insn</code> |
28 * {@link #visitLabel} | {@link #visitTryCatchBlock} | {@link #visitLocalVariable} | {@link #visitLineNumber})*
29 * {@link #visitMaxStack}] {@link #visitEnd}.
30 * <p>
31 * In addition, the <code>visit<i>X</i>Insn</code> and <code>visitLabel</code> methods are called in the sequential
32 * order of the bytecode instructions of the visited code, <code>visitTryCatchBlock</code> is called <i>before</i> the
33 * labels passed as arguments have been visited, and the <code>visitLocalVariable</code> and
34 * <code>visitLineNumber</code> methods are called <i>after</i> the labels passed as arguments have been visited.
35 */
36 public class MethodVisitor extends BaseWriter {
37 protected MethodVisitor() {
38 }
39
40 protected MethodVisitor(@NonNull ConstantPoolGeneration cp, int methodAccess) {
41 super(cp, methodAccess);
42 }
43
44 /**
45 * Visits an annotation on a parameter of the method being visited.
46 *
47 * @param parameter
48 * the parameter index
49 * @param desc
50 * the descriptor of the annotation type
51 *
52 * @return a visitor to visit the annotation values, or <code>null</code> if this visitor is not interested in
53 * visiting this annotation
54 */
55 @Nullable
56 public AnnotationVisitor visitParameterAnnotation(@NonNegative int parameter, @NonNull String desc) {
57 return null;
58 }
59
60 /**
61 * Visits a zero operand instruction.
62 *
63 * @param opcode
64 * the {@linkplain Opcodes opcode} of the instruction to be visited: NOP, ACONST_NULL, ICONST_M1,
65 * ICONST_0 ICONST_0 to ICONST_5, LCONST_0, LCONST_1, FCONST_0 to FCONST_2, DCONST_0, DCONST_1, IALOAD,
66 * LALOAD, FALOAD, DALOAD, AALOAD, BALOAD, CALOAD, SALOAD, IASTORE, LASTORE, FASTORE, DASTORE, AASTORE,
67 * BASTORE, CASTORE, SASTORE, POP, POP2, DUP, DUP_X1, DUP_X2, DUP2, DUP2_X1, DUP2_X2, SWAP, IADD, LADD,
68 * FADD, DADD, ISUB, LSUB, FSUB, DSUB, IMUL, LMUL, FMUL, DMUL, IDIV, LDIV, FDIV, DDIV, IREM, LREM, FREM,
69 * DREM, INEG, LNEG, FNEG, DNEG, ISHL, LSHL, ISHR, LSHR, IUSHR, LUSHR, IAND, LAND, IOR, LOR, IXOR, LXOR,
70 * I2L, I2F, I2D, L2I, L2F, L2D, F2I, F2L, F2D, D2I, D2L, D2F, I2B, I2C, I2S, LCMP, FCMPL, FCMPG, DCMPL,
71 * DCMPG, IRETURN, LRETURN, FRETURN, DRETURN, ARETURN, RETURN, ARRAYLENGTH, ATHROW, MONITORENTER, or
72 * MONITOREXIT
73 */
74 public void visitInsn(int opcode) {
75 }
76
77 /**
78 * Visits an instruction with a single <code>int</code> operand.
79 *
80 * @param opcode
81 * the {@linkplain Opcodes opcode} of the instruction to be visited: BIPUSH, SIPUSH, or NEWARRAY
82 * @param operand
83 * the operand of the instruction to be visited: when opcode is BIPUSH, it's between
84 * {@link Byte#MIN_VALUE} and {@link Byte#MAX_VALUE}; when opcode is SIPUSH, it's between
85 * {@link Short#MIN_VALUE} and {@link Short#MAX_VALUE}; when opcode is NEWARRAY, the operand value is one
86 * of the {@link ArrayElementType} values
87 */
88 public void visitIntInsn(int opcode, int operand) {
89 }
90
91 /**
92 * Visits a local variable instruction, which loads or stores the value of a local variable.
93 *
94 * @param opcode
95 * the {@linkplain Opcodes opcode} of the local variable instruction to be visited: ILOAD, LLOAD, FLOAD,
96 * DLOAD, ALOAD, ISTORE, LSTORE, FSTORE, DSTORE, ASTORE or RET
97 * @param varIndex
98 * the operand of the instruction to be visited, which is the index of a local variable
99 */
100 public void visitVarInsn(int opcode, @NonNegative int varIndex) {
101 }
102
103 /**
104 * Visits a type instruction, which takes the internal name of a class as parameter.
105 *
106 * @param opcode
107 * the {@linkplain Opcodes opcode} of the instruction to be visited: NEW, ANEWARRAY, CHECKCAST, or
108 * INSTANCEOF
109 * @param typeDesc
110 * the operand of the instruction, which is the internal name of an object or array class
111 */
112 public void visitTypeInsn(int opcode, @NonNull String typeDesc) {
113 }
114
115 /**
116 * Visits a field access instruction, which loads or stores the value of a field of an object or a class.
117 *
118 * @param opcode
119 * the {@linkplain Opcodes opcode} of the instruction to be visited: GETSTATIC, PUTSTATIC, GETFIELD, or
120 * PUTFIELD
121 * @param owner
122 * the internal name of the field's owner class
123 * @param name
124 * the field's name
125 * @param desc
126 * the field's descriptor (see {@link JavaType})
127 */
128 public void visitFieldInsn(int opcode, @NonNull String owner, @NonNull String name, @NonNull String desc) {
129 }
130
131 /**
132 * Visits a method invocation instruction, which invokes a method or constructor.
133 *
134 * @param opcode
135 * the {@linkplain Opcodes opcode} of the instruction: INVOKEVIRTUAL, INVOKESPECIAL, INVOKESTATIC, or
136 * INVOKEINTERFACE
137 * @param owner
138 * the internal name of the method's owner class
139 * @param name
140 * the method's name
141 * @param desc
142 * the method's descriptor (see {@link JavaType})
143 * @param itf
144 * whether the method's owner class is an interface or not
145 */
146 public void visitMethodInsn(int opcode, @NonNull String owner, @NonNull String name, @NonNull String desc,
147 boolean itf) {
148 }
149
150 /**
151 * Visits an {@link Opcodes#INVOKEDYNAMIC INVOKEDYNAMIC} instruction.
152 *
153 * @param name
154 * the method's name
155 * @param desc
156 * the method's descriptor (see {@link JavaType})
157 * @param bsm
158 * the bootstrap method
159 * @param bsmArgs
160 * the bootstrap method constant arguments, where each argument must be an {@link Integer},
161 * {@link Float}, {@link Long}, {@link Double}, {@link String}, {@link JavaType}, or {@link MethodHandle}
162 * value
163 */
164 public void visitInvokeDynamicInsn(@NonNull String name, @NonNull String desc, @NonNull MethodHandle bsm,
165 @NonNull Object... bsmArgs) {
166 }
167
168 /**
169 * Visits a jump instruction.
170 *
171 * @param opcode
172 * the {@linkplain Opcodes opcode} of the jump instruction to be visited: IFEQ, IFNE, IFLT, IFGE, IFGT,
173 * IFLE, IF_ICMPEQ, IF_ICMPNE, IF_ICMPLT, IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ACMPEQ, IF_ACMPNE, GOTO,
174 * JSR, IFNULL, or IFNONNULL
175 * @param label
176 * the operand of the instruction to be visited, which is a label that designates the instruction to
177 * which the jump instruction may jump
178 */
179 public void visitJumpInsn(int opcode, @NonNull Label label) {
180 }
181
182 /**
183 * Visits a label, which designates the instruction that will be visited just after it.
184 */
185 public void visitLabel(@NonNull Label label) {
186 }
187
188 /**
189 * Visits a {@link Opcodes#LDC LDC} instruction.
190 *
191 * @param cst
192 * the constant to be loaded on the stack, which must be a non null
193 * {@link Integer}/{@link Float}/{@link Long}/{@link Double}/{@link String}, an {@link ObjectType} or
194 * {@link ArrayType} for <code>.class</code> constants, a {@link MethodType}, or a {@link MethodHandle}
195 */
196 public void visitLdcInsn(@NonNull Object cst) {
197 }
198
199 /**
200 * Visits an {@link Opcodes#IINC IINC} instruction.
201 *
202 * @param varIndex
203 * index of the local variable to be incremented
204 * @param increment
205 * amount to increment the local variable by
206 */
207 public void visitIincInsn(@NonNegative int varIndex, int increment) {
208 }
209
210 /**
211 * Visits a {@link Opcodes#TABLESWITCH TABLESWITCH} instruction.
212 *
213 * @param min
214 * the minimum key value
215 * @param max
216 * the maximum key value
217 * @param dflt
218 * beginning of the default handler block
219 * @param labels
220 * beginnings of the handler blocks; <code>labels[i]</code> is the beginning of the handler block for the
221 * <code>min + i</code> key
222 */
223 public void visitTableSwitchInsn(int min, int max, @NonNull Label dflt, @NonNull Label... labels) {
224 }
225
226 /**
227 * Visits a {@link Opcodes#LOOKUPSWITCH LOOKUPSWITCH} instruction.
228 *
229 * @param dflt
230 * beginning of the default handler block
231 * @param keys
232 * the values of the keys
233 * @param labels
234 * beginnings of the handler blocks; <code>labels[i]</code> is the beginning of the handler block for the
235 * <code>keys[i]</code>
236 */
237 public void visitLookupSwitchInsn(@NonNull Label dflt, @NonNull int[] keys, @NonNull Label[] labels) {
238 }
239
240 /**
241 * Visits a {@link Opcodes#MULTIANEWARRAY MULTIANEWARRAY} instruction.
242 *
243 * @param desc
244 * an array type descriptor (see {@link ArrayType})
245 * @param dims
246 * number of dimensions of the array to allocate
247 */
248 public void visitMultiANewArrayInsn(@NonNull String desc, @NonNegative int dims) {
249 }
250
251 /**
252 * Visits a <code>try..catch</code> block.
253 *
254 * @param start
255 * beginning of the exception handler's scope (inclusive)
256 * @param end
257 * end of the exception handler's scope (exclusive)
258 * @param handler
259 * beginning of the exception handler's code
260 * @param type
261 * internal name of the type of exceptions handled by the handler, or <code>null</code> to catch any
262 * exceptions (for "finally" blocks)
263 */
264 public void visitTryCatchBlock(@NonNull Label start, @NonNull Label end, @NonNull Label handler,
265 @Nullable String type) {
266 }
267
268 /**
269 * Visits a local variable declaration.
270 *
271 * @param name
272 * the name of the local variable
273 * @param desc
274 * the type descriptor of the local variable
275 * @param signature
276 * the type signature of the local variable; <code>null</code> when the local variable type does not use
277 * generic types
278 * @param start
279 * the first instruction corresponding to the scope of this local variable (inclusive)
280 * @param end
281 * the last instruction corresponding to the scope of this local variable (exclusive)
282 * @param index
283 * the local variable's index
284 */
285 public void visitLocalVariable(@NonNull String name, @NonNull String desc, @Nullable String signature,
286 @NonNull Label start, @NonNull Label end, @NonNegative int index) {
287 }
288
289 /**
290 * Visits a line number within the body of the method.
291 *
292 * @param line
293 * a line number, which refers to the source file from which the class was compiled
294 * @param start
295 * the first instruction corresponding to this line number
296 */
297 public void visitLineNumber(@NonNegative int line, @NonNull Label start) {
298 }
299
300 /**
301 * Visits the maximum stack size of the method.
302 */
303 public void visitMaxStack(@NonNegative int maxStack) {
304 }
305 }