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  ;
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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags