001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 * 017 */ 018package org.apache.bcel.verifier.structurals; 019 020 021import java.util.ArrayList; 022 023import org.apache.bcel.generic.InstructionHandle; 024 025/** 026 * An InstructionContext offers convenient access 027 * to information like control flow successors and 028 * such. 029 * 030 */ 031public interface InstructionContext{ 032 033 /** 034 * The getTag and setTag methods may be used for 035 * temporary flagging, such as graph colouring. 036 * Nothing in the InstructionContext object depends 037 * on the value of the tag. JustIce does not use it. 038 * 039 * @see #setTag(int tag) 040 */ 041 int getTag(); 042 043 /** 044 * The getTag and setTag methods may be used for 045 * temporary flagging, such as graph colouring. 046 * Nothing in the InstructionContext object depends 047 * on the value of the tag. JustIce does not use it. 048 * 049 * @see #getTag() 050 */ 051 void setTag(int tag); 052 053 /** 054 * This method symbolically executes the Instruction 055 * held in the InstructionContext. 056 * It "merges in" the incoming execution frame situation 057 * (see The Java Virtual Machine Specification, 2nd 058 * edition, page 146). 059 * By so doing, the outgoing execution frame situation 060 * is calculated. 061 * 062 * This method is JustIce-specific and is usually of 063 * no sense for users of the ControlFlowGraph class. 064 * They should use getInstruction().accept(Visitor), 065 * possibly in conjunction with the ExecutionVisitor. 066 * 067 * 068 * @see ControlFlowGraph 069 * @see ExecutionVisitor 070 * @see #getOutFrame(ArrayList) 071 * @return true - if and only if the "outgoing" frame situation 072 * changed from the one before execute()ing. 073 */ 074 boolean execute(Frame inFrame, ArrayList<InstructionContext> executionPredecessors, 075 InstConstraintVisitor icv, ExecutionVisitor ev); 076 077 Frame getInFrame(); 078 079 /** 080 * This method returns the outgoing execution frame situation; 081 * therefore <B>it has to be calculated by execute(Frame, ArrayList) 082 * first.</B> 083 * 084 * @see #execute(Frame, ArrayList, InstConstraintVisitor, ExecutionVisitor) 085 */ 086 Frame getOutFrame(ArrayList<InstructionContext> executionPredecessors); 087 088 /** 089 * Returns the InstructionHandle this InstructionContext is wrapped around. 090 * 091 * @return The InstructionHandle this InstructionContext is wrapped around. 092 */ 093 InstructionHandle getInstruction(); 094 095 /** 096 * Returns the usual control flow successors. 097 * @see #getExceptionHandlers() 098 */ 099 InstructionContext[] getSuccessors(); 100 101 /** 102 * Returns the exception handlers that protect this instruction. 103 * They are special control flow successors. 104 */ 105 ExceptionHandler[] getExceptionHandlers(); 106}