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 * @version $Id: InstructionContext.java 1806200 2017-08-25 16:33:06Z ggregory $
031 */
032public interface InstructionContext{
033
034    /**
035     * The getTag and setTag methods may be used for
036     * temporary flagging, such as graph colouring.
037     * Nothing in the InstructionContext object depends
038     * on the value of the tag. JustIce does not use it.
039     *
040     * @see #setTag(int tag)
041     */
042    int getTag();
043
044    /**
045     * The getTag and setTag methods may be used for
046     * temporary flagging, such as graph colouring.
047     * Nothing in the InstructionContext object depends
048     * on the value of the tag. JustIce does not use it.
049     *
050     * @see #getTag()
051     */
052    void setTag(int tag);
053
054    /**
055     * This method symbolically executes the Instruction
056     * held in the InstructionContext.
057     * It "merges in" the incoming execution frame situation
058     * (see The Java Virtual Machine Specification, 2nd
059     * edition, page 146).
060     * By so doing, the outgoing execution frame situation
061     * is calculated.
062     *
063     * This method is JustIce-specific and is usually of
064     * no sense for users of the ControlFlowGraph class.
065     * They should use getInstruction().accept(Visitor),
066     * possibly in conjunction with the ExecutionVisitor.
067     *
068     *
069     * @see ControlFlowGraph
070     * @see ExecutionVisitor
071     * @see #getOutFrame(ArrayList)
072     * @return true -  if and only if the "outgoing" frame situation
073     * changed from the one before execute()ing.
074     */
075    boolean execute(Frame inFrame, ArrayList<InstructionContext> executionPredecessors,
076            InstConstraintVisitor icv, ExecutionVisitor ev);
077
078    Frame getInFrame();
079
080    /**
081     * This method returns the outgoing execution frame situation;
082     * therefore <B>it has to be calculated by execute(Frame, ArrayList)
083     * first.</B>
084     *
085     * @see #execute(Frame, ArrayList, InstConstraintVisitor, ExecutionVisitor)
086     */
087    Frame getOutFrame(ArrayList<InstructionContext> executionPredecessors);
088
089    /**
090     * Returns the InstructionHandle this InstructionContext is wrapped around.
091     *
092     * @return The InstructionHandle this InstructionContext is wrapped around.
093     */
094    InstructionHandle getInstruction();
095
096    /**
097     * Returns the usual control flow successors.
098     * @see #getExceptionHandlers()
099     */
100    InstructionContext[] getSuccessors();
101
102    /**
103     * Returns the exception handlers that protect this instruction.
104     * They are special control flow successors.
105     */
106    ExceptionHandler[] getExceptionHandlers();
107}