edu.umd.cs.findbugs.ba

Class Frame<ValueType>

public abstract class Frame<ValueType> extends Object

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

Constructor Summary
Frame(int numLocals)
Constructor.
Method Summary
Collection<ValueType>allSlots()
voidclearStack()
Clear the Java operand stack.
voidcopyFrom(Frame<ValueType> other)
Make this Frame exactly the same as the one given as a parameter.
ValueTypegetArgument(InvokeInstruction ins, ConstantPoolGen cpg, int i, SignatureParser sigParser)
Get the ith argument passed to given method invocation.
BitSetgetArgumentSet(InvokeInstruction invokeInstruction, ConstantPoolGen cpg, DataflowValueChooser<ValueType> chooser)
Get set of arguments passed to a method invocation which match given predicate.
intgetArgumentSlot(int i, int numArguments)
Get the stack slot that will contain given method argument.
ValueTypegetInstance(Instruction ins, ConstantPoolGen cpg)
Get the value corresponding to the object instance used in the given instruction.
intgetInstanceSlot(Instruction ins, ConstantPoolGen cpg)
Get the slot the object instance referred to by given instruction is located in.
intgetInstanceStackLocation(Instruction ins, ConstantPoolGen cpg)
Get the stack location (counting down from top of stack, starting at 0) containing the object instance referred to by given instruction.
intgetLastUpdateTimestamp()
intgetNumArguments(InvokeInstruction ins, ConstantPoolGen cpg)
Get the number of arguments passed to given method invocation.
intgetNumArgumentsIncludingObjectInstance(InvokeInstruction ins, ConstantPoolGen cpg)
Get the number of arguments passed to given method invocation, including the object instance if the call is to an instance method.
intgetNumLocals()
Get the number of locals.
intgetNumSlots()
Get the number of slots (locals plus stack values).
ValueTypegetOperand(StackConsumer ins, ConstantPoolGen cpg, int i)
Get the ith operand used by given instruction.
intgetStackDepth()
Get the depth of the Java operand stack.
intgetStackLocation(int loc)
Get a the location in the frame of a value on the operand stack.
ValueTypegetStackValue(int loc)
Get a value on the operand stack.
voidgetTopStackWords(ValueType[] valueList)
Get the values on the top of the Java operand stack.
ValueTypegetTopValue()
Get the value on the top of the Java operand stack.
ValueTypegetValue(int n)
Get the value at the nth slot.
booleanisBottom()
Return whether or not this object is the special "BOTTOM" value for Frames.
booleanisTop()
Return whether or not this object the special "TOP" value for Frames.
booleanisValid()
Is the frame valid (meaning it is not TOP or BOTTOM)?
ValueTypepopValue()
Pop a value off of the Java operand stack.
voidpushValue(ValueType value)
Push a value onto the Java operand stack.
booleansameAs(Frame<ValueType> other)
Return true if this stack frame is the same as the one given as a parameter.
voidsetBottom()
Make this Frame the special "BOTTOM" value.
voidsetLastUpdateTimestamp(int lastUpdateTimestamp)
voidsetTop()
Make this frame the special "TOP" value.
voidsetValid()
Set the Frame to be valid (neither TOP nor BOTTOM).
voidsetValue(int n, ValueType value)
Set the value at the nth slot.
protected StringvalueToString(ValueType value)
Subclasses may override this if they want to do something special to convert Value objects to Strings.

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

allSlots

public Collection<ValueType> allSlots()

Returns: an unmodifiable Collection of the local variable and operand stack slots

clearStack

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

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

getArgument

public ValueType getArgument(InvokeInstruction ins, ConstantPoolGen cpg, int i, SignatureParser sigParser)
Get the ith argument passed to given method invocation.

Parameters: ins the method invocation instruction cpg the ConstantPoolGen for the class containing the method i index of the argument; 0 for the first argument, etc.

Returns: the ith argument

Throws: DataflowAnalysisException

getArgumentSet

public BitSet getArgumentSet(InvokeInstruction invokeInstruction, ConstantPoolGen cpg, DataflowValueChooser<ValueType> chooser)
Get set of arguments passed to a method invocation which match given predicate.

Parameters: invokeInstruction the InvokeInstruction cpg the ConstantPoolGen chooser predicate to choose which argument values should be in the returned set

Returns: BitSet specifying which arguments match the predicate, indexed by argument number (starting from 0)

Throws: DataflowAnalysisException

getArgumentSlot

public int getArgumentSlot(int i, int numArguments)
Get the stack slot that will contain given method argument. Assumes that this frame is at the location (just before) a method invocation instruction.

Parameters: i the argument index: 0 for first arg, etc. numArguments total number of arguments to the called method

Returns: slot containing the argument value

getInstance

public ValueType getInstance(Instruction ins, ConstantPoolGen cpg)
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

getInstanceSlot

public int getInstanceSlot(Instruction ins, ConstantPoolGen cpg)
Get the slot the object instance referred to by given instruction is located in.

Parameters: ins the Instruction cpg the ConstantPoolGen for the method

Returns: stack slot the object instance is in

Throws: DataflowAnalysisException

getInstanceStackLocation

public int getInstanceStackLocation(Instruction ins, ConstantPoolGen cpg)
Get the stack location (counting down from top of stack, starting at 0) containing the object instance referred to by 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.

The value returned may be passed to getStackValue(int).

Parameters: ins the Instruction cpg the ConstantPoolGen for the method

Returns: stack location (counting down from top of stack, starting at 0) containing the object instance

Throws: DataflowAnalysisException

getLastUpdateTimestamp

public int getLastUpdateTimestamp()

Returns: Returns the lastUpdateTimestamp.

getNumArguments

public int getNumArguments(InvokeInstruction ins, ConstantPoolGen cpg)
Get the number of arguments passed to given method invocation.

Parameters: ins the method invocation instruction cpg the ConstantPoolGen for the class containing the method

Returns: number of arguments; note that this excludes the object instance for instance methods

Throws: DataflowAnalysisException

getNumArgumentsIncludingObjectInstance

public int getNumArgumentsIncludingObjectInstance(InvokeInstruction ins, ConstantPoolGen cpg)
Get the number of arguments passed to given method invocation, including the object instance if the call is to an instance method.

Parameters: ins the method invocation instruction cpg the ConstantPoolGen for the class containing the method

Returns: number of arguments, including object instance if appropriate

Throws: DataflowAnalysisException

getNumLocals

public int getNumLocals()
Get the number of locals.

getNumSlots

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

getOperand

public ValueType getOperand(StackConsumer ins, ConstantPoolGen cpg, int i)
Get the ith operand used by given instruction.

Parameters: ins the instruction, which must be a StackConsumer cpg the ConstantPoolGen i index of operand to get: 0 for the first operand, etc.

Returns: the ith operand used by the given instruction

Throws: DataflowAnalysisException

getStackDepth

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

getStackLocation

public int getStackLocation(int loc)
Get a the location in the frame of a value on the operand stack.

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

getStackValue

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

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

getTopStackWords

public void getTopStackWords(ValueType[] valueList)
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.

getTopValue

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

Throws: DataflowAnalysisException if the Java operand stack is empty

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

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.

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.

isValid

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

popValue

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

Returns: the value that was popped

Throws: DataflowAnalysisException if the Java operand stack is empty

pushValue

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

Parameters: value the ValueType to push

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

setBottom

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

setLastUpdateTimestamp

public void setLastUpdateTimestamp(int lastUpdateTimestamp)

Parameters: lastUpdateTimestamp The lastUpdateTimestamp to set.

setTop

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

setValid

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

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

valueToString

protected 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.
FindBugs™ is licenced under the LGPL. Copyright © 2006 University of Maryland.