KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > tc > 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 com.tc.asm.tree.analysis;
31
32 import java.util.List JavaDoc;
33
34 import com.tc.asm.Type;
35 import com.tc.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 <tt>equal</tt> to the given value.
84      * @throws AnalyzerException if an error occured during the interpretation.
85      */

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

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

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

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

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

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