KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > asm > tree > analysis > Interpreter


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 org.objectweb.asm.tree.analysis;
31
32 import java.util.List JavaDoc;
33
34 import org.objectweb.asm.Type;
35 import org.objectweb.asm.tree.AbstractInsnNode;
36
37 /**
38  * A semantic bytecode interpreter. More precisely, this interpreter only
39  * manages the computation of values from other values: it does not manage the
40  * transfer of values to or from the stack, and to or from the local variables.
41  * This separation allows a generic bytecode {@link Analyzer} to work with
42  * various semantic interpreters, without needing to duplicate the code to
43  * simulate the transfer of values.
44  *
45  * @author Eric Bruneton
46  */

47 public interface Interpreter {
48
49     /**
50      * Creates a new value that represents the given type.
51      *
52      * @param type a primitive or reference type, or <tt>null</tt> to
53      * represent an uninitialized value.
54      * @return a value that represents the given type. The size of the returned
55      * value must be equal to the size of the given type.
56      */

57     Value newValue(Type type);
58
59     /**
60      * Interprets a bytecode instruction without arguments. This method is
61      * called for the following opcodes:
62      *
63      * ACONST_NULL, ICONST_M1, ICONST_0, ICONST_1, ICONST_2, ICONST_3, ICONST_4,
64      * ICONST_5, LCONST_0, LCONST_1, FCONST_0, FCONST_1, FCONST_2, DCONST_0,
65      * DCONST_1, BIPUSH, SIPUSH, LDC, JSR, GETSTATIC, NEW
66      *
67      * @param insn the bytecode instruction to be interpreted.
68      * @return the result of the interpretation of the given instruction.
69      * @throws AnalyzerException if an error occured during the interpretation.
70      */

71     Value newOperation(AbstractInsnNode insn) throws AnalyzerException;
72
73     /**
74      * Interprets a bytecode instruction that moves a value on the stack or to
75      * or from local variables. This method is called for the following opcodes:
76      *
77      * ILOAD, LLOAD, FLOAD, DLOAD, ALOAD, ISTORE, LSTORE, FSTORE, DSTORE,
78      * ASTORE, DUP, DUP_X1, DUP_X2, DUP2, DUP2_X1, DUP2_X2, SWAP
79      *
80      * @param insn the bytecode instruction to be interpreted.
81      * @param value the value that must be moved by the instruction.
82      * @return the result of the interpretation of the given instruction. The
83      * returned value must be {@link Value#equals(Value) equal} to the
84      * given value.
85      * @throws AnalyzerException if an error occured during the interpretation.
86      */

87     Value copyOperation(AbstractInsnNode insn, Value value)
88             throws AnalyzerException;
89
90     /**
91      * Interprets a bytecode instruction with a single argument. This method is
92      * called for the following opcodes:
93      *
94      * INEG, LNEG, FNEG, DNEG, IINC, I2L, I2F, I2D, L2I, L2F, L2D, F2I, F2L,
95      * F2D, D2I, D2L, D2F, I2B, I2C, I2S, IFEQ, IFNE, IFLT, IFGE, IFGT, IFLE,
96      * TABLESWITCH, LOOKUPSWITCH, IRETURN, LRETURN, FRETURN, DRETURN, ARETURN,
97      * PUTSTATIC, GETFIELD, NEWARRAY, ANEWARRAY, ARRAYLENGTH, ATHROW, CHECKCAST,
98      * INSTANCEOF, MONITORENTER, MONITOREXIT, IFNULL, IFNONNULL
99      *
100      * @param insn the bytecode instruction to be interpreted.
101      * @param value the argument of the instruction to be interpreted.
102      * @return the result of the interpretation of the given instruction.
103      * @throws AnalyzerException if an error occured during the interpretation.
104      */

105     Value unaryOperation(AbstractInsnNode insn, Value value)
106             throws AnalyzerException;
107
108     /**
109      * Interprets a bytecode instruction with two arguments. This method is
110      * called for the following opcodes:
111      *
112      * IALOAD, LALOAD, FALOAD, DALOAD, AALOAD, BALOAD, CALOAD, SALOAD, IADD,
113      * LADD, FADD, DADD, ISUB, LSUB, FSUB, DSUB, IMUL, LMUL, FMUL, DMUL, IDIV,
114      * LDIV, FDIV, DDIV, IREM, LREM, FREM, DREM, ISHL, LSHL, ISHR, LSHR, IUSHR,
115      * LUSHR, IAND, LAND, IOR, LOR, IXOR, LXOR, LCMP, FCMPL, FCMPG, DCMPL,
116      * DCMPG, IF_ICMPEQ, IF_ICMPNE, IF_ICMPLT, IF_ICMPGE, IF_ICMPGT, IF_ICMPLE,
117      * IF_ACMPEQ, IF_ACMPNE, PUTFIELD
118      *
119      * @param insn the bytecode instruction to be interpreted.
120      * @param value1 the first argument of the instruction to be interpreted.
121      * @param value2 the second argument of the instruction to be interpreted.
122      * @return the result of the interpretation of the given instruction.
123      * @throws AnalyzerException if an error occured during the interpretation.
124      */

125     Value binaryOperation(AbstractInsnNode insn, Value value1, Value value2)
126             throws AnalyzerException;
127
128     /**
129      * Interprets a bytecode instruction with three arguments. This method is
130      * called for the following opcodes:
131      *
132      * IASTORE, LASTORE, FASTORE, DASTORE, AASTORE, BASTORE, CASTORE, SASTORE
133      *
134      * @param insn the bytecode instruction to be interpreted.
135      * @param value1 the first argument of the instruction to be interpreted.
136      * @param value2 the second argument of the instruction to be interpreted.
137      * @param value3 the third argument of the instruction to be interpreted.
138      * @return the result of the interpretation of the given instruction.
139      * @throws AnalyzerException if an error occured during the interpretation.
140      */

141     Value ternaryOperation(
142         AbstractInsnNode insn,
143         Value value1,
144         Value value2,
145         Value value3) throws AnalyzerException;
146
147     /**
148      * Interprets a bytecode instruction with a variable number of arguments.
149      * This method is called for the following opcodes:
150      *
151      * INVOKEVIRTUAL, INVOKESPECIAL, INVOKESTATIC, INVOKEINTERFACE,
152      * MULTIANEWARRAY
153      *
154      * @param insn the bytecode instruction to be interpreted.
155      * @param values the arguments of the instruction to be interpreted.
156      * @return the result of the interpretation of the given instruction.
157      * @throws AnalyzerException if an error occured during the interpretation.
158      */

159     Value naryOperation(AbstractInsnNode insn, List JavaDoc values)
160             throws AnalyzerException;
161
162     /**
163      * Merges two values. The merge operation must return a value that
164      * represents both values (for instance, if the two values are two types,
165      * the merged value must be a common super type of the two types. If the two
166      * values are integer intervals, the merged value must be an interval that
167      * contains the previous ones. Likewise for other types of values).
168      *
169      * @param v a value.
170      * @param w another value.
171      * @return the merged value. If the merged value is equal to <tt>v</tt>,
172      * this method <i>must</i> return <tt>v</tt>.
173      */

174     Value merge(Value v, Value w);
175 }
176
Popular Tags