    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}