View Javadoc

1   /*
2    * Copyright  2000-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License"); 
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License. 
15   *
16   */ 
17  package org.apache.bcel.verifier.structurals;
18  
19  
20  import java.util.ArrayList;
21  import org.apache.bcel.generic.InstructionHandle;
22  
23  /***
24   * An InstructionContext offers convenient access
25   * to information like control flow successors and
26   * such.
27   *
28   * @version $Id: InstructionContext.java 382272 2006-03-02 03:31:46Z tcurdt $
29   * @author Enver Haase
30   */
31  public interface InstructionContext{
32  
33  	/***
34  	 * The getTag and setTag methods may be used for
35  	 * temporary flagging, such as graph colouring.
36  	 * Nothing in the InstructionContext object depends
37  	 * on the value of the tag. JustIce does not use it.
38  	 * 
39  	 * @see #setTag(int tag)
40  	 */
41  	public int getTag();
42  
43  	/***
44  	 * The getTag and setTag methods may be used for
45  	 * temporary flagging, such as graph colouring.
46  	 * Nothing in the InstructionContext object depends
47  	 * on the value of the tag. JustIce does not use it.
48  	 * 
49  	 * @see #getTag()
50  	 */
51  	public void setTag(int tag);
52  
53  	/***
54  	 * This method symbolically executes the Instruction
55  	 * held in the InstructionContext.
56  	 * It "merges in" the incoming execution frame situation
57  	 * (see The Java Virtual Machine Specification, 2nd
58  	 * edition, page 146).
59  	 * By so doing, the outgoing execution frame situation
60  	 * is calculated.
61  	 *
62  	 * This method is JustIce-specific and is usually of
63  	 * no sense for users of the ControlFlowGraph class.
64  	 * They should use getInstruction().accept(Visitor),
65  	 * possibly in conjunction with the ExecutionVisitor.
66  	 * 
67  	 *
68  	 * @see ControlFlowGraph
69  	 * @see ExecutionVisitor
70  	 * @see #getOutFrame(ArrayList)
71  	 * @return true -  if and only if the "outgoing" frame situation
72  	 * changed from the one before execute()ing.
73  	 */
74  	boolean execute(Frame inFrame, ArrayList executionPredecessors, InstConstraintVisitor icv, ExecutionVisitor ev);
75  
76  	Frame getInFrame();
77  
78  	/***
79  	 * This method returns the outgoing execution frame situation;
80  	 * therefore <B>it has to be calculated by execute(Frame, ArrayList)
81  	 * first.</B>
82  	 *
83  	 * @see #execute(Frame, ArrayList, InstConstraintVisitor, ExecutionVisitor)
84  	 */
85  	Frame getOutFrame(ArrayList executionPredecessors);
86  	
87  	/***
88  	 * Returns the InstructionHandle this InstructionContext is wrapped around.
89  	 *
90  	 * @return The InstructionHandle this InstructionContext is wrapped around.
91  	 */
92  	InstructionHandle getInstruction();
93  
94  	/***
95  	 * Returns the usual control flow successors.
96  	 * @see #getExceptionHandlers()
97  	 */
98  	InstructionContext[] getSuccessors();
99  
100 	/***
101 	 * Returns the exception handlers that protect this instruction.
102 	 * They are special control flow successors.
103 	 */
104 	ExceptionHandler[] getExceptionHandlers();
105 }