edu.umd.cs.findbugs.ba
Class Frame<ValueType>

java.lang.Object
  extended by edu.umd.cs.findbugs.ba.Frame<ValueType>
All Implemented Interfaces:
Debug
Direct Known Subclasses:
BetterTypeFrame, IsNullValueFrame, ResourceValueFrame, TypeFrame, ValueNumberFrame

public abstract class Frame<ValueType>
extends java.lang.Object
implements Debug

Generic class for representing a Java stack frame as a dataflow value. A frame consists of "slots", which represent the local variables and values on the Java operand stack. Slots 0 .. getNumLocals() - 1 represent the local variables. Slots getNumLocals() .. getNumSlots() - 1 represent the Java operand stack.

Frame is parametized by "ValueType", which is the type of value to be stored in the Frame's slots. This type must form a lattice, according to the abstract mergeValues() operation in the corresponding analysis class (which should be derived from FrameDataflowAnalysis). When a Frame is constructed, all of its slots will contain null. The analysis is responsible for initializing created Frames with default values at the appropriate time. Typically, only initEntryFact() will need to do this.

A Frame may have the special "TOP" value. Such frames serve as the identity element for the meet operation operation.

A Frame may have the special "BOTTOM" value. The result of merging any frame with BOTTOM is BOTTOM.

Author:
David Hovemeyer
See Also:
FrameDataflowAnalysis

Field Summary
private static int DEFAULT_STACK_CAPACITY
          Default number of stack slots to preallocate space for.
private  boolean isBottom
          Flag marking this frame as a special "BOTTOM" value.
private  boolean isTop
          Flag marking this frame as a special "TOP" value.
private  int numLocals
          Number of local variables in the method.
private  java.util.ArrayList<ValueType> slotList
          Array storing the values of local variables and operand stack slots.
private static boolean STACK_ONLY
           
 
Fields inherited from interface edu.umd.cs.findbugs.ba.Debug
CHECK_ASSERTIONS, VERIFY_INTEGRITY
 
Constructor Summary
Frame(int numLocals)
          Constructor.
 
Method Summary
 void clearStack()
          Clear the Java operand stack.
 void copyFrom(Frame<ValueType> other)
          Make this Frame exactly the same as the one given as a parameter.
 ValueType getInstance(org.apache.bcel.generic.Instruction ins, org.apache.bcel.generic.ConstantPoolGen cpg)
          Get the value corresponding to the object instance used in the given instruction.
 int getNumLocals()
          Get the number of locals.
 int getNumSlots()
          Get the number of slots (locals plus stack values).
 int getStackDepth()
          Get the depth of the Java operand stack.
 ValueType getStackValue(int loc)
          Get a value on the operand stack.
 void getTopStackWords(ValueType[] valueList)
          Get the values on the top of the Java operand stack.
 ValueType getTopValue()
          Get the value on the top of the Java operand stack.
 ValueType getValue(int n)
          Get the value at the nth slot.
 boolean isBottom()
          Return whether or not this object is the special "BOTTOM" value for Frames.
 boolean isTop()
          Return whether or not this object the special "TOP" value for Frames.
 boolean isValid()
          Is the frame valid (meaning it is not TOP or BOTTOM)?
 ValueType popValue()
          Pop a value off of the Java operand stack.
 void pushValue(ValueType value)
          Push a value onto the Java operand stack.
 boolean sameAs(Frame<ValueType> other)
          Return true if this stack frame is the same as the one given as a parameter.
 void setBottom()
          Make this Frame the special "BOTTOM" value.
 void setTop()
          Make this frame the special "TOP" value.
 void setValid()
          Set the Frame to be valid (neither TOP nor BOTTOM).
 void setValue(int n, ValueType value)
          Set the value at the nth slot.
 java.lang.String toString()
          Convert to string.
protected  java.lang.String valueToString(ValueType value)
          Subclasses may override this if they want to do something special to convert Value objects to Strings.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

numLocals

private int numLocals
Number of local variables in the method.


slotList

private java.util.ArrayList<ValueType> slotList
Array storing the values of local variables and operand stack slots.


isTop

private boolean isTop
Flag marking this frame as a special "TOP" value. Such Frames serve as the identity element when merging.


isBottom

private boolean isBottom
Flag marking this frame as a special "BOTTOM" value. Such Frames arise when merging two frames of different size.


DEFAULT_STACK_CAPACITY

private static final int DEFAULT_STACK_CAPACITY
Default number of stack slots to preallocate space for.

See Also:
Constant Field Values

STACK_ONLY

private static final boolean STACK_ONLY
Constructor Detail

Frame

public Frame(int numLocals)
Constructor. This version of the constructor is for subclasses for which it is always safe to call getDefaultValue(), even when the object is not fully initialized.

Parameters:
numLocals - number of local variable slots in the method
Method Detail

isTop

public boolean isTop()
Return whether or not this object the special "TOP" value for Frames. Such Frames are the identity element of the meet operation.


setTop

public void setTop()
Make this frame the special "TOP" value. Such Frames are the identity element of the meet operation.


isBottom

public boolean isBottom()
Return whether or not this object is the special "BOTTOM" value for Frames. Such Frames arise when merging two frames of different size.


setBottom

public void setBottom()
Make this Frame the special "BOTTOM" value. Such Frames arise when merging two frames of different size.


setValid

public void setValid()
Set the Frame to be valid (neither TOP nor BOTTOM).


isValid

public boolean isValid()
Is the frame valid (meaning it is not TOP or BOTTOM)?


pushValue

public void pushValue(ValueType value)
Push a value onto the Java operand stack.

Parameters:
value - the ValueType to push

popValue

public ValueType popValue()
                   throws DataflowAnalysisException
Pop a value off of the Java operand stack.

Returns:
the value that was popped
Throws:
DataflowAnalysisException - if the Java operand stack is empty

getTopValue

public ValueType getTopValue()
                      throws DataflowAnalysisException
Get the value on the top of the Java operand stack.

Throws:
DataflowAnalysisException - if the Java operand stack is empty

getTopStackWords

public void getTopStackWords(ValueType[] valueList)
                      throws DataflowAnalysisException
Get the values on the top of the Java operand stack. The top stack item is placed at the end of the array, so that to restore the values to the stack, you would push them in the order they appear in the array.

Throws:
DataflowAnalysisException

getStackValue

public ValueType getStackValue(int loc)
                        throws DataflowAnalysisException
Get a value on the operand stack.

Parameters:
loc - the stack location, counting downwards from the top (location 0)
Throws:
DataflowAnalysisException

getInstance

public ValueType getInstance(org.apache.bcel.generic.Instruction ins,
                             org.apache.bcel.generic.ConstantPoolGen cpg)
                      throws DataflowAnalysisException
Get the value corresponding to the object instance used in the given instruction. This relies on the observation that in instructions which use an object instance (such as getfield, invokevirtual, etc.), the object instance is the first operand used by the instruction.

Parameters:
ins - the instruction
cpg - the ConstantPoolGen for the method
Throws:
DataflowAnalysisException

clearStack

public void clearStack()
Clear the Java operand stack. Only local variable slots will remain in the frame.


getStackDepth

public int getStackDepth()
Get the depth of the Java operand stack.


getNumLocals

public int getNumLocals()
Get the number of locals.


getNumSlots

public int getNumSlots()
Get the number of slots (locals plus stack values).


getValue

public ValueType getValue(int n)
Get the value at the nth slot.

Parameters:
n - the slot to get the value of
Returns:
the value in the slot

setValue

public void setValue(int n,
                     ValueType value)
Set the value at the nth slot.

Parameters:
n - the slot in which to set a new value
value - the value to set

sameAs

public boolean sameAs(Frame<ValueType> other)
Return true if this stack frame is the same as the one given as a parameter.

Parameters:
other - the other Frame
Returns:
true if the frames are the same, false otherwise

copyFrom

public void copyFrom(Frame<ValueType> other)
Make this Frame exactly the same as the one given as a parameter.

Parameters:
other - the Frame to make this object the same as

toString

public java.lang.String toString()
Convert to string.

Overrides:
toString in class java.lang.Object

valueToString

protected java.lang.String valueToString(ValueType value)
Subclasses may override this if they want to do something special to convert Value objects to Strings. By default, we just call toString() on the values.