edu.uci.eecs.doc.cascade.tree
Class Tree

java.lang.Object
  edu.uci.eecs.doc.cascade.tree.Tree

All Implemented Interfaces:

Iterable<Node>

public class Tree
extends Object
implements Iterable<Node>

A control flow tree of a Java method or part of a Java method. This data structure is nearly identical to a control flow graph (CFG), but having a tree structure, it can be parsed more easily and can be displayed in a manner that closely resembles the original source code structure.

Author:

Trevor Harmon

Method Summary

boolean	equals(Object obj) Compares this tree to the specified object.
Tree	getCallerTree() Returns a handle to the control flow tree that invoked this control flow tree.
List<String>	getClassPath() Returns the class path that was specified when the tree was created.
List<InstructionHandle>	getInstructions() Returns the complete list of instructions that correspond to this tree's method.
Tree	getInvokedTree(InstructionHandle instructionHandle) Returns a control flow tree representing the method that the given invocation instruction invokes.
Field	getInvokingField() Returns a handle to the field that was used to invoke this control flow tree.
Method	getMethod() Returns the method from which this control flow tree was constructed.
Set<Method>	getMethodInvocations() Returns the methods that this tree invokes.
Set<Method>	getMethodInvocations(Node startNode) Returns the methods that the given node invokes.
Node	getRootNode() Returns the node at the top of the control flow tree (the entry point).
Tree	getRootTree() Returns the control flow tree at the top of the call graph.
int	hashCode() Returns a hash code for this tree.
Iterator<Node>	iterator() Returns an iterator that will walk through every node of this control flow tree.
static Tree	load(List<String> classPath, Method method, Tree callerTree, Field invokingField) Creates a new control flow tree.
String	toString() Returns a simple one-line string describing the method represented by this tree.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

load

public static Tree load(List<String> classPath,
                        Method method,
                        Tree callerTree,
                        Field invokingField)
                 throws IOException,
                        NoSuchMethodException,
                        ClassNotFoundException

Creates a new control flow tree. This static factory method implements a cache mechanism so that the same tree isn't regenerated over and over again. It assumes that Tree objects are immutable.

Parameters:

classPath - a list of directories that will be searched when loading classes during control flow construction

method - the method whose control flow tree should be created

callerTree - a control flow tree that invoked this tree (or null if this is the root tree)

invokingField - the field used to invoke this tree (or null if no field was used)

Throws:

IOException - if the method cannot be loaded

NoSuchMethodException - if the method cannot be found

ClassNotFoundException - if a class in the control flow cannot be loaded

getRootNode

public Node getRootNode()

Returns the node at the top of the control flow tree (the entry point).

Returns:

the root of the tree

getRootTree

public Tree getRootTree()

Returns the control flow tree at the top of the call graph. For example, given the following code:

 void methodA() {
   methodB();
 }
 void methodB() {
   methodC();
 }
 void methodC() {}
 

This method will return A's control flow tree if invoked on a tree representing method B or C.

Returns:

a control flow tree

getMethod

public Method getMethod()

Returns the method from which this control flow tree was constructed.

Returns:

the Java method that this tree represents

getCallerTree

public Tree getCallerTree()

Returns a handle to the control flow tree that invoked this control flow tree.

Returns:

a control flow tree, or null if this tree was not invoked by another tree

getInvokingField

public Field getInvokingField()

Returns a handle to the field that was used to invoke this control flow tree. For example, if a class contains a field called myField, and this tree was invoked with the expression myField.myMethod(), then this method will return a handle to myField. Returns null if this tree was invoked without using a field (e.g., a local variable).

Returns:

a handle to the field used to invoke this method, or null if no field was used

getClassPath

public List<String> getClassPath()

Returns the class path that was specified when the tree was created.

Returns:

a list of directories

getMethodInvocations

public Set<Method> getMethodInvocations()

Returns the methods that this tree invokes.

Returns:

a set of Java method handles, or an empty set if this tree does not invoke any methods

getMethodInvocations

public Set<Method> getMethodInvocations(Node startNode)

Returns the methods that the given node invokes. Unlike Node.getMethodInvocations(), the returned set includes method invocations in sub-scopes. For example, consider the following code:

 if (isAvailable())
 {
     requestMessage();
 }
 

Calling Node.getMethodInvocations() on this if-then-else node would return only isAvailable(). However, if Tree.getMethodInvocations() were called with the if-then-else node as a parameter, the returned set would include both isAvailable() and requestMessage().

Parameters:

startNode - a node in a control flow tree

Returns:

a set of Java method handles, or an empty set if this node does not invoke any methods

getInvokedTree

public Tree getInvokedTree(InstructionHandle instructionHandle)

Returns a control flow tree representing the method that the given invocation instruction invokes.

Parameters:

instructionHandle - a handle to an invocation instruction (instructionHandle.getInstruction() must be of type InvokeInstruction)

Returns:

a control flow tree, or null if no tree corresponds to the given instruction

getInstructions

public List<InstructionHandle> getInstructions()

Returns the complete list of instructions that correspond to this tree's method.

Returns:

a list of bytecode instructions

iterator

public Iterator<Node> iterator()

Returns an iterator that will walk through every node of this control flow tree.

Specified by:

iterator in interface Iterable<Node>

Returns:

a control flow tree iterator

equals

public boolean equals(Object obj)

Compares this tree to the specified object. The result is true if and only if the argument is a Tree object for the same method that this tree represents.

Overrides:

equals in class Object

Parameters:

obj - the object to compare this tree against

Returns:

true if the given object represents a tree equivalent to this tree; false otherwise

hashCode

public int hashCode()

Returns a hash code for this tree. The hash code is identical to the hashcode of the method that this tree represents.

Overrides:

hashCode in class Object

Returns:

a hash code for this tree

toString

public String toString()

Returns a simple one-line string describing the method represented by this tree.

Overrides:

toString in class Object

Returns:

a string representation of this tree