The joeq system allows access to
program code at a wide variety of levels. This document will cover the
important methods of each level of focus. Where appropriate, links to the
relevant joeq javadocs
will be available.
The Class package contains classes that represent the
various components of Java class files. Many of the String-like return values
in this package return objects of type Utf8, explicitly representing the
Unicode format the JVM uses; these may be turned back into Strings by calling toString upon them.
jq_Type is the basic type representing types. It
has a subclass, jq_Primitive,
representing the primitive types. The jq_Primitive class has the following static fields for
referring to each type:
Neither jq_Type nor jq_Primitive have any methods of interest to us.
Arrays are represented with the jq_Array class. The methods of note here are:
int getDimensionality(): Returns how many dimensions the
array has: int[][] is dimensionality
2. jq_Type getElementType(): Returns the element type. int[][] has element type int[]. jq_Type
getInnermostElementType(): Returns the result of the maximum number of nested getElementType() calls. int[][] has innermost element type int. The jq_Class class represents a class file as a whole.
You acquire the jq_Class for a
type by calling joeq.Main.Helper.load; see the section on joeq.Main.Helper for details. Important methods in jq_Class are:
String getName(): Returns the name of the class. jq_Class getSuperclass(): Returns the parent class, or null if the class is java.lang.Object. jq_Class[]
getDeclaredInterfaces(): Returns an array of all interfaces this class claims to implement.
This does not include superinterfaces of those interfaces, nor does it
contain interfaces declared by superclasses. jq_Field[]
getDeclaredInstanceFields(): Returns all instance fields that this class declares. It does not
mention fields declared by superclasses. jq_Field[]
getDeclaredStaticFields(): Returns all static fields that this class declares. It does not
mention fields declared by superclasses. jq_Method[]
getDeclaredVirtualMethods(): Returns all instance methods that this class declares. It does not
mention methods declared by superclasses. jq_Method[]
getDeclaredStaticMethods(): Returns all static methods that this class declares. It does not
mention methods declared by superclasses. Utf8 getName(): Returns the (simple) name of this
method. jq_Type[] getParamTypes(): The arguments to the routine. jq_Type getReturnType(): The return type of the routine. jq_Class getDeclaringClass(): Returns the class that declared
this method. Utf8 getName(): Name of the field. Doesn't include
the class designator. jq_Type getType(): The type of this field's value. jq_Class getDeclaringClass(): Returns the class that declared
this field. Most of the code for representing
actual program code in joeq is contained in the joeq.Compiler package and its
subpackages.
BasicBlock entry(): The first BasicBlock in the CFG.
(This is always empty.) BasicBlock exit(): The last BasicBlock in the CFG.
(This is also always empty.) jq_Method getMethod(): The method that corresponds to this
CFG. The QuadIterator loops through a ControlFlowGraph a Quad at a time. It is constructed
taking a ControlFlowGraph
as its constructor argument. The following methods then become available:
Quad nextQuad(): Returns the next quad in a
reverse-post-order listing of Quads. Quad previousQuad(): Returns the previous quad in a
reverse-post-order listing of Quads. boolean hasNext(): Returns true if nextQuad is legal. boolean hasPrevious(): Returns true if previousQuad is legal. java.util.Iterator
successors(): Returns
an iterator of the possible successor quads of the most recently returned
quad. If a possible successor is the method exit, it includes the null value in the iteration. java.util.Iterator
predecessors():
Returns an iterator of the possible predecessor quads of the most recently
returned quad. If a possible predecessor is the method entrance, it
includes the null value in the iteration. The BasicBlock class represents a joeq basic block.
These have one entrance, and, assuming no exceptions are thrown, one exit. (If
exceptions are thrown, the "basic block" may have multiple
exit points.)
There are no methods of interest
to us defined in BasicBlock. We
will usually be focussing either on ControlFlowGraphs or Quads.
At the bottom of the code
hierarchy is the quad, a construct very similar to three-address
assembly code. Relevant methods on quads themselves are:
Operator getOperator(): retrieve the Operator for this
Quad. You are unlikely to ever check this directly, as the use of a QuadVisitor will usually do this for you. List getThrownExceptions: Returns a list of jq_Classes - one for each exception that can
be thrown. toString: A textual mnemonic for this quad. The Operators and Operands of
Quads are numerous enough that they they warrant their
own web page: the Quad Overview.
This package deals mostly with
the JVM's code representation -- we don't have to deal with it in this class.
Note, however, that it has a ControlFlowGraph class of its own, so do not import joeq.Compiler.Quad.* and joeq.Compiler.BytecodeAnalysis.* in the same code.