# Class Subroutines

java.lang.Object
org.apache.bcel.verifier.structurals.Subroutines

public class Subroutines extends Object
Instances of this class contain information about the subroutines found in a code array of a method. This implementation considers the top-level (the instructions reachable without a JSR or JSR_W starting off from the first instruction in a code array of a method) being a special subroutine; see getTopLevel() for that. Please note that the definition of subroutines in the Java Virtual Machine Specification, Second Edition is somewhat incomplete. Therefore, JustIce uses an own, more rigid notion. Basically, a subroutine is a piece of code that starts at the target of a JSR of JSR_W instruction and ends at a corresponding RET instruction. Note also that the control flow of a subroutine may be complex and non-linear; and that subroutines may be nested. JustIce also mandates subroutines not to be protected by exception handling code (for the sake of control flow predictability). To understand JustIce's notion of subroutines, please read TODO: refer to the paper.

See Also:
  - `getTopLevel()`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final Subroutine`
  `TOPLEVEL`
  This is referring to a special subroutine, namely the top level.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Subroutines(MethodGen mg)`
  Constructs a new instance.
  `Subroutines(MethodGen mg, boolean enableJustIceCheck)`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Subroutine`
  `getSubroutine(InstructionHandle leader)`
  Returns the Subroutine object associated with the given leader (that is, the first instruction of the subroutine).
  `Subroutine`
  `getTopLevel()`
  For easy handling, the piece of code that is not a subroutine, the top-level, is also modeled as a Subroutine object.
  `Subroutine`
  `subroutineOf(InstructionHandle any)`
  Returns the subroutine object associated with the given instruction.
  `String`
  `toString()`
  Returns a String representation of this object; merely for debugging puposes.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### TOPLEVEL

    public final Subroutine TOPLEVEL
    This is referring to a special subroutine, namely the top level. This is not really a subroutine but we use it to distinguish between top level instructions and unreachable instructions.

- ## Constructor Details

  - ### Subroutines

    public Subroutines(MethodGen mg)
    Constructs a new instance.
    Parameters:
      `mg` - A MethodGen object representing method to create the Subroutine objects of. Assumes that JustIce strict checks are needed.

  - ### Subroutines

    public Subroutines(MethodGen mg, boolean enableJustIceCheck)
    Constructs a new instance.
    Parameters:
      `mg` - A MethodGen object representing method to create the Subroutine objects of.
      `enableJustIceCheck` - whether to enable additional JustIce checks
    Since:
      6.0

- ## Method Details

  - ### getSubroutine

    public Subroutine getSubroutine(InstructionHandle leader)
    Returns the Subroutine object associated with the given leader (that is, the first instruction of the subroutine). You must not use this to get the top-level instructions modeled as a Subroutine object.
    See Also:
      - `getTopLevel()`

  - ### getTopLevel

    public Subroutine getTopLevel()
    For easy handling, the piece of code that is not a subroutine, the top-level, is also modeled as a Subroutine object. It is a special Subroutine object where you must not invoke getEnteringJsrInstructions() or getLeavingRET().
    See Also:
      - `Subroutine.getEnteringJsrInstructions()`
      - `Subroutine.getLeavingRET()`

  - ### subroutineOf

    public Subroutine subroutineOf(InstructionHandle any)
    Returns the subroutine object associated with the given instruction. This is a costly operation, you should consider using getSubroutine(InstructionHandle). Returns 'null' if the given InstructionHandle lies in so-called 'dead code', i.e. code that can never be executed.
    See Also:
      - `getSubroutine(InstructionHandle)`
      - `getTopLevel()`

  - ### toString

    public String toString()
    Returns a String representation of this object; merely for debugging puposes.
    Overrides:
      `toString` in class `Object`