Top Description Inners Fields Constructors Methods
org.apache.bcel.verifier.structurals

public Class Subroutines

extends Object
Class Inheritance
Imports
java.util.ArrayList, .HashMap, .HashSet, .List, .Map, .Set, org.apache.bcel.generic.ASTORE, .ATHROW, .BranchInstruction, .CodeExceptionGen, .GotoInstruction, .IndexedInstruction, .Instruction, .InstructionHandle, .JsrInstruction, .LocalVariableInstruction, .MethodGen, .RET, .ReturnInstruction, .Select, org.apache.bcel.verifier.exc.AssertionViolatedException, .StructuralCodeConstraintException
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()

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static enum
Subroutines.ColourConstants

private class
Subroutines.SubroutineImpl

This inner class implements the Subroutine interface.

Field Summary

Modifier and TypeField and Description
private final Map<InstructionHandle, Subroutine>
subroutines

The map containing the subroutines found.

public final Subroutine
TOPLEVEL

This is referring to a special subroutine, namely the top level.

Constructor Summary

AccessConstructor and Description
public
Subroutines(final MethodGen
A MethodGen object representing method to create the Subroutine objects of. Assumes that JustIce strict checks are needed.
mg)

Constructs a new instance.

public
Subroutines(final MethodGen
A MethodGen object representing method to create the Subroutine objects of.
mg, final boolean
whether to enable additional JustIce checks
enableJustIceCheck)

Constructs a new instance.

Method Summary

Modifier and TypeMethod and Description
public Subroutine
getSubroutine(final InstructionHandle leader)

Returns the Subroutine object associated with the given leader (that is, the first instruction of the subroutine).

private static InstructionHandle[]
getSuccessors(final InstructionHandle instruction)

A utility method that calculates the successors of a given InstructionHandle in the same subroutine.

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.

private void
noRecursiveCalls(final Subroutine sub, final Set<Integer> set)

This (recursive) utility method makes sure that no subroutine is calling a subroutine that uses the same local variable for the RET as themselves (recursively).

public Subroutine
subroutineOf(final InstructionHandle any)

Returns the subroutine object associated with the given instruction.

public String
toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object; merely for debugging puposes.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

subroutinesback to summary
private final Map<InstructionHandle, Subroutine> subroutines

The map containing the subroutines found. Key: InstructionHandle of the leader of the subroutine. Elements: SubroutineImpl objects.

TOPLEVELback to summary
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 Detail

Subroutinesback to summary
public Subroutines(final MethodGen mg)

Constructs a new instance.

Parameters
mg:MethodGen

A MethodGen object representing method to create the Subroutine objects of. Assumes that JustIce strict checks are needed.

Subroutinesback to summary
public Subroutines(final MethodGen mg, final boolean enableJustIceCheck)

Constructs a new instance.

Parameters
mg:MethodGen

A MethodGen object representing method to create the Subroutine objects of.

enableJustIceCheck:boolean

whether to enable additional JustIce checks

Since
6.0

Method Detail

getSubroutineback to summary
public Subroutine getSubroutine(final 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()
getSuccessorsback to summary
private static InstructionHandle[] getSuccessors(final InstructionHandle instruction)

A utility method that calculates the successors of a given InstructionHandle in the same subroutine. That means, a RET does not have any successors as defined here. A JsrInstruction has its physical successor as its successor (opposed to its target) as defined here.

getTopLevelback to summary
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()
noRecursiveCallsback to summary
private void noRecursiveCalls(final Subroutine sub, final Set<Integer> set)

This (recursive) utility method makes sure that no subroutine is calling a subroutine that uses the same local variable for the RET as themselves (recursively). This includes that subroutines may not call themselves recursively, even not through intermediate calls to other subroutines.

Exceptions
StructuralCodeConstraintException:
if the above constraint is not satisfied.
subroutineOfback to summary
public Subroutine subroutineOf(final 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()
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object; merely for debugging puposes.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override
org.apache.bcel.verifier.structurals back to summary

private final Enum Subroutines.ColourConstants

extends Enum<Subroutines.ColourConstants>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final Subroutines.ColourConstants
BLACK

public static final Subroutines.ColourConstants
GRAY

public static final Subroutines.ColourConstants
WHITE

Constructor Summary

AccessConstructor and Description
private
ColourConstants()

Method Summary

Modifier and TypeMethod and Description
public static Subroutines.ColourConstants
valueOf(String name)

public static Subroutines.ColourConstants[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

BLACKback to summary
public static final Subroutines.ColourConstants BLACK
GRAYback to summary
public static final Subroutines.ColourConstants GRAY
WHITEback to summary
public static final Subroutines.ColourConstants WHITE

Constructor Detail

ColourConstantsback to summary
private ColourConstants()

Method Detail

valueOfback to summary
public static Subroutines.ColourConstants valueOf(String name)
valuesback to summary
public static Subroutines.ColourConstants[] values()
org.apache.bcel.verifier.structurals back to summary

private final Class Subroutines.SubroutineImpl

extends Object
implements Subroutine
Class Inheritance
  • java.lang.Object
  • org.apache.bcel.verifier.structurals.Subroutines.SubroutineImpl
All Implemented Interfaces
org.apache.bcel.verifier.structurals.Subroutine
This inner class implements the Subroutine interface.

Field Summary

Modifier and TypeField and Description
private final Subroutines.SubroutineImpl[]
EMPTY_ARRAY

private final Set<InstructionHandle>
instructions

The instructions that belong to this subroutine.

private int
localVariable

The Local Variable slot where the first instruction of this subroutine (an ASTORE) stores the JsrInstruction's ReturnAddress in and the RET of this subroutine operates on.

private final Set<InstructionHandle>
theJSRs

The JSR or JSR_W instructions that define this subroutine by targeting it.

private InstructionHandle
theRET

The RET instruction that leaves this subroutine.

private static final int
UNSET

UNSET, a symbol for an uninitialized localVariable field.

Constructor Summary

AccessConstructor and Description
public
SubroutineImpl()

The default constructor.

Method Summary

Modifier and TypeMethod and Description
public void
addEnteringJsrInstruction(final InstructionHandle jsrInst)

Adds a new JSR or JSR_W that has this subroutine as its target.

pack-priv void
addInstruction(final InstructionHandle ih)

public boolean
contains(final InstructionHandle
The InstructionHandle to test.
inst)

Implements org.apache.bcel.verifier.structurals.Subroutine.contains.

Returns if the given InstructionHandle refers to an instruction that is part of this subroutine.
public int[]
getAccessedLocalsIndices()

Implements org.apache.bcel.verifier.structurals.Subroutine.getAccessedLocalsIndices.

Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed, write-accessed or both); local variables referenced by subroutines of this subroutine are not included.
public InstructionHandle[]
getEnteringJsrInstructions()

Implements org.apache.bcel.verifier.structurals.Subroutine.getEnteringJsrInstructions.

Returns all the JsrInstructions that have the first instruction of this subroutine as their target.
public InstructionHandle[]
getInstructions()

Implements org.apache.bcel.verifier.structurals.Subroutine.getInstructions.

Returns all instructions that together form this subroutine.
public InstructionHandle
getLeavingRET()

Implements org.apache.bcel.verifier.structurals.Subroutine.getLeavingRET.

Returns the one and only RET that leaves the subroutine.
public int[]
getRecursivelyAccessedLocalsIndices()

Implements org.apache.bcel.verifier.structurals.Subroutine.getRecursivelyAccessedLocalsIndices.

Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed, write-accessed or both); local variables referenced by subroutines of this subroutine are included.
private void
getRecursivelyAccessedLocalsIndicesHelper(final Set<Integer> set, final Subroutine[] subs)

A recursive helper method for getRecursivelyAccessedLocalsIndices().

pack-priv void
setLeavingRET()

Sets the leaving RET instruction.

pack-priv void
setLocalVariable(final int i)

public Subroutine[]
subSubs()

Implements org.apache.bcel.verifier.structurals.Subroutine.subSubs.

Returns the subroutines that are directly called from this subroutine.
public String
toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object, merely for debugging purposes.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

EMPTY_ARRAYback to summary
private final Subroutines.SubroutineImpl[] EMPTY_ARRAY
instructionsback to summary
private final Set<InstructionHandle> instructions

The instructions that belong to this subroutine.

localVariableback to summary
private int localVariable

The Local Variable slot where the first instruction of this subroutine (an ASTORE) stores the JsrInstruction's ReturnAddress in and the RET of this subroutine operates on.

theJSRsback to summary
private final Set<InstructionHandle> theJSRs

The JSR or JSR_W instructions that define this subroutine by targeting it.

theRETback to summary
private InstructionHandle theRET

The RET instruction that leaves this subroutine.

UNSETback to summary
private static final int UNSET

UNSET, a symbol for an uninitialized localVariable field. This is used for the "top-level" Subroutine; i.e. no subroutine.

Constructor Detail

SubroutineImplback to summary
public SubroutineImpl()

The default constructor.

Method Detail

addEnteringJsrInstructionback to summary
public void addEnteringJsrInstruction(final InstructionHandle jsrInst)

Adds a new JSR or JSR_W that has this subroutine as its target.

addInstructionback to summary
pack-priv void addInstruction(final InstructionHandle ih)
containsback to summary
public boolean contains(final InstructionHandle inst)

Implements org.apache.bcel.verifier.structurals.Subroutine.contains.

Doc from org.apache.bcel.verifier.structurals.Subroutine.contains.

Returns if the given InstructionHandle refers to an instruction that is part of this subroutine. This is a convenience method that saves iteration over the InstructionHandle objects returned by getInstructions().

Parameters
inst:InstructionHandle

The InstructionHandle to test.

Returns:boolean

Whether the given InstructionHandle refers to an instruction that is part of this subroutine.

Annotations
@Override
getAccessedLocalsIndicesback to summary
public int[] getAccessedLocalsIndices()

Implements org.apache.bcel.verifier.structurals.Subroutine.getAccessedLocalsIndices.

Doc from org.apache.bcel.verifier.structurals.Subroutine.getAccessedLocalsIndices.

Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed, write-accessed or both); local variables referenced by subroutines of this subroutine are not included.

Returns:int[]

An int[] containing the indices of the local variable slots.

Annotations
@Override
getEnteringJsrInstructionsback to summary
public InstructionHandle[] getEnteringJsrInstructions()

Implements org.apache.bcel.verifier.structurals.Subroutine.getEnteringJsrInstructions.

Doc from org.apache.bcel.verifier.structurals.Subroutine.getEnteringJsrInstructions.

Returns all the JsrInstructions that have the first instruction of this subroutine as their target. Must not be invoked on the 'top-level subroutine'.

Returns:InstructionHandle[]

The JsrInstructions that have the first instruction of this subroutine as their target.

Annotations
@Override
getInstructionsback to summary
public InstructionHandle[] getInstructions()

Implements org.apache.bcel.verifier.structurals.Subroutine.getInstructions.

Doc from org.apache.bcel.verifier.structurals.Subroutine.getInstructions.

Returns all instructions that together form this subroutine. Note that an instruction is part of exactly one subroutine (the top-level code is considered to be a special subroutine) - else it is not reachable at all (dead code).

Returns:InstructionHandle[]

All instructions that together form this subroutine.

Annotations
@Override
getLeavingRETback to summary
public InstructionHandle getLeavingRET()

Implements org.apache.bcel.verifier.structurals.Subroutine.getLeavingRET.

Doc from org.apache.bcel.verifier.structurals.Subroutine.getLeavingRET.

Returns the one and only RET that leaves the subroutine. Note that JustIce has a pretty rigid notion of a subroutine. Must not be invoked on the 'top-level subroutine'.

Returns:InstructionHandle

The one and only RET that leaves the subroutine.

Annotations
@Override
getRecursivelyAccessedLocalsIndicesback to summary
public int[] getRecursivelyAccessedLocalsIndices()

Implements org.apache.bcel.verifier.structurals.Subroutine.getRecursivelyAccessedLocalsIndices.

Doc from org.apache.bcel.verifier.structurals.Subroutine.getRecursivelyAccessedLocalsIndices.

Returns an int[] containing the indices of the local variable slots accessed by this Subroutine (read-accessed, write-accessed or both); local variables referenced by subroutines of this subroutine are included.

Returns:int[]

An int[] containing the indices of the local variable slots.

Annotations
@Override
getRecursivelyAccessedLocalsIndicesHelperback to summary
private void getRecursivelyAccessedLocalsIndicesHelper(final Set<Integer> set, final Subroutine[] subs)

A recursive helper method for getRecursivelyAccessedLocalsIndices().

See Also
getRecursivelyAccessedLocalsIndices()
setLeavingRETback to summary
pack-priv void setLeavingRET()

Sets the leaving RET instruction. Must be invoked after all instructions are added. Must not be invoked for top-level 'subroutine'.

setLocalVariableback to summary
pack-priv void setLocalVariable(final int i)
subSubsback to summary
public Subroutine[] subSubs()

Implements org.apache.bcel.verifier.structurals.Subroutine.subSubs.

Doc from org.apache.bcel.verifier.structurals.Subroutine.subSubs.

Returns the subroutines that are directly called from this subroutine.

Returns:Subroutine[]

The subroutines that are directly called from this subroutine.

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a String representation of this object, merely for debugging purposes. (Internal) Warning: Verbosity on a problematic subroutine may cause stack overflow errors due to recursive subSubs() calls. Don't use this, then.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override