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