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 */
017package org.apache.bcel.verifier.structurals;
018
019import org.apache.bcel.generic.InstructionHandle;
020
021/**
022 * This interface defines properties of JVM bytecode subroutines. Note that it is 'abused' to maintain the top-level
023 * code in a consistent fashion, too.
024 */
025public interface Subroutine {
026
027    /**
028     * Returns if the given InstructionHandle refers to an instruction that is part of this subroutine. This is a
029     * convenience method that saves iteration over the InstructionHandle objects returned by getInstructions().
030     *
031     * @param inst The InstructionHandle to test.
032     * @return Whether the given InstructionHandle refers to an instruction that is part of this subroutine.
033     *
034     * @see #getInstructions()
035     */
036    boolean contains(InstructionHandle inst);
037
038    /**
039     * Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed,
040     * write-accessed or both); local variables referenced by subroutines of this subroutine are not included.
041     *
042     * @return An int[] containing the indices of the local variable slots.
043     * @see #getRecursivelyAccessedLocalsIndices()
044     */
045    int[] getAccessedLocalsIndices();
046
047    /**
048     * Returns all the JsrInstructions that have the first instruction of this subroutine as their target. <B>Must not be
049     * invoked on the 'top-level subroutine'.</B>
050     *
051     * @return The JsrInstructions that have the first instruction of this subroutine as their target.
052     */
053    InstructionHandle[] getEnteringJsrInstructions();
054
055    /**
056     * Returns all instructions that together form this subroutine. Note that an instruction is part of exactly one
057     * subroutine (the top-level code is considered to be a special subroutine) - else it is not reachable at all (dead
058     * code).
059     *
060     * @return All instructions that together form this subroutine.
061     */
062    InstructionHandle[] getInstructions();
063
064    /**
065     * Returns the one and only RET that leaves the subroutine. Note that JustIce has a pretty rigid notion of a subroutine.
066     * <B>Must not be invoked on the 'top-level subroutine'.</B>
067     *
068     * @return The one and only RET that leaves the subroutine.
069     *
070     * @see Subroutines
071     */
072    InstructionHandle getLeavingRET();
073
074    /**
075     * Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed,
076     * write-accessed or both); local variables referenced by subroutines of this subroutine are included.
077     *
078     * @return An int[] containing the indices of the local variable slots.
079     * @see #getAccessedLocalsIndices()
080     */
081    int[] getRecursivelyAccessedLocalsIndices();
082
083    /**
084     * Returns the subroutines that are directly called from this subroutine.
085     *
086     * @return The subroutines that are directly called from this subroutine.
087     */
088    Subroutine[] subSubs();
089}