Top Description Fields Constructors Methods
org.aspectj.apache.bcel.generic

public Class InstructionList

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.ByteArrayOutputStream, .DataOutputStream, .IOException, .Serializable, java.util.ArrayList, .HashMap, .Iterator, .List, .Set, org.aspectj.apache.bcel.Constants, org.aspectj.apache.bcel.classfile.Constant, .ConstantPool, org.aspectj.apache.bcel.util.ByteSequence

This class is a container for a list of Instruction objects. Instructions can be appended, inserted, moved, deleted, etc.. Instructions are being wrapped into InstructionHandles objects that are returned upon append/insert operations. They give the user (read only) access to the list structure, such that it can be traversed and manipulated in a controlled way. A list is finally dumped to a byte code array with getByteCode.
Authors
M. Dahm, Abraham Nevado
Version
$Id: InstructionList.java,v 1.12 2011/09/02 22:33:04 aclement Exp $
See Also
Instruction, InstructionHandle, BranchHandle

Field Summary

Modifier and TypeField and Description
private InstructionHandle
private int
private int[]
private InstructionHandle

Constructor Summary

AccessConstructor and Description
public
public
public
InstructionList(byte[]
byte array containing the instructions
code
)

Initialize instruction list from byte array.

Method Summary

Modifier and TypeMethod and Description
public InstructionHandle

Returns:

instruction handle pointing to the first appended instruction
append
(InstructionHandle
where to append the instruction list
appendTo
,
InstructionList
Instruction list to append to this one
appendee
)

Append another list after instruction (handle) ih contained in this list.

public InstructionHandle

Returns:

instruction handle pointing to the first appended instruction
append
(Instruction
where to append the instruction list
i
,
InstructionList
Instruction list to append to this one
il
)

Append another list after instruction i contained in this list.

public InstructionHandle

Returns:

instruction handle of the first appended instruction
append
(InstructionList
list to append to end of this list
il
)

Append another list to this one.

private void
append(InstructionHandle
instruction to append
ih
)

Append an instruction to the end of this list.

public InstructionHandle

Returns:

instruction handle of the appended instruction
append
(Instruction
instruction to append
i
)

Append an instruction to the end of this list.

public BranchHandle

Returns:

branch instruction handle of the appended instruction
append
(InstructionBranch
branch instruction to append
i
)

Append a branch instruction to the end of this list.

public InstructionHandle

Returns:

instruction handle of the first appended instruction
append
(Instruction
Instruction in list
i
,
Instruction
Instruction to append after i in list
j
)

Append a single instruction j after another instruction i, which must be in this list of course!

public InstructionHandle

Returns:

instruction handle pointing to the first appended instruction
append
(InstructionHandle
where to append the instruction list
ih
,
Instruction
Instruction to append
i
)

Append an instruction after instruction (handle) ih contained in this list.

public BranchHandle

Returns:

instruction handle pointing to the first appended instruction
append
(InstructionHandle
where to append the instruction list
ih
,
InstructionBranch
Instruction to append
i
)

Append an instruction after instruction (handle) ih contained in this list.

public InstructionHandle
public InstructionHandle
public InstructionHandle
private void
private void
public boolean
public boolean
public InstructionList

Returns:

complete, i.e., deep copy of this list
copy
()

public void
delete(InstructionHandle
instruction (handle) to remove
ih
)

Remove instruction from this list.

public void
delete(InstructionHandle
where to start deleting (inclusive)
from
,
InstructionHandle
where to end deleting (inclusive)
to
)

Remove instructions from instruction `from' to instruction `to' contained in this list.

public void
delete(Instruction
where to start deleting (inclusive)
from
,
Instruction
where to end deleting (inclusive)
to
)

Remove instructions from instruction `from' to instruction `to' contained in this list.

public void
dispose()

Delete contents of list.

public static InstructionHandle
findHandle(InstructionHandle[] ihs, int[] pos, int count, int target)

public static InstructionHandle

Returns:

target position's instruction handle if available
findHandle
(InstructionHandle[]
array of instruction handles, i.e. il.getInstructionHandles()
ihs
,
int[]
array of positions corresponding to ihs, i.e. il.getInstructionPositions()
pos
,
int
length of arrays
count
,
int
target position to search for
target
,
boolean returnClosestIfNoExactMatch)

Find the target instruction (handle) that corresponds to the given target position (byte code offset).

public InstructionHandle

Returns:

target position's instruction handle if available
findHandle
(int
byte code position to search for
pos
)

Get instruction handle for instruction at byte code position pos.

public InstructionHandle
findHandle(int pos, InstructionHandle[] instructionArray)

public InstructionHandle
findHandle(int pos, InstructionHandle[] instructionArray, boolean useClosestApproximationIfNoExactFound)

private InstructionHandle

Returns:

instruction found on success, null otherwise
findInstruction1
(Instruction
instruction to search for
i
)

Search for given Instruction reference, start at beginning of list.

private InstructionHandle

Returns:

instruction found on success, null otherwise
findInstruction2
(Instruction
instruction to search for
i
)

Search for given Instruction reference, start at end of list

public byte[]

Returns:

the byte code ready to be dumped
getByteCode
()

When everything is finished, use this method to convert the instruction list into an array of bytes.

public InstructionHandle

Returns:

end of list
getEnd
()

public InstructionHandle[]

Returns:

array containing all instructions (handles)
getInstructionHandles
()

public int[]

Returns:

array containing all instruction's offset in byte code
getInstructionPositions
()

Get positions (offsets) of all instructions in the list.

public Instruction[]

Returns:

an array of instructions without target information for branch instructions.
getInstructions
()

public InstructionHandle[]
public int

Returns:

length of list (Number of instructions, not bytes)
getLength
()

public InstructionHandle

Returns:

start of list
getStart
()

public InstructionHandle

Returns:

instruction handle of the first inserted instruction
insert
(InstructionHandle
where to append the instruction list
ih
,
InstructionList
Instruction list to insert
il
)

Insert another list before Instruction handle ih contained in this list.

public InstructionHandle

Returns:

instruction handle of the first inserted instruction
insert
(InstructionList
list to insert before start of this list
il
)

Insert another list.

private void
insert(InstructionHandle
instruction to insert
ih
)

Insert an instruction at start of this list.

public InstructionHandle

Returns:

instruction handle pointing to the first inserted instruction, i.e., il.getStart()
insert
(Instruction
where to append the instruction list
i
,
InstructionList
Instruction list to insert
il
)

Insert another list before Instruction i contained in this list.

public InstructionHandle

Returns:

instruction handle of the inserted instruction
insert
(Instruction
instruction to insert
i
)

Insert an instruction at start of this list.

public BranchHandle

Returns:

branch instruction handle of the appended instruction
insert
(InstructionBranch
branch instruction to insert
i
)

Insert a branch instruction at start of this list.

public InstructionHandle

Returns:

instruction handle of the first inserted instruction
insert
(Instruction
Instruction in list
i
,
Instruction
Instruction to insert before i in list
j
)

Insert a single instruction j before another instruction i, which must be in this list of course!

public InstructionHandle

Returns:

instruction handle of the first inserted instruction
insert
(InstructionHandle
where to insert to the instruction list
ih
,
Instruction
Instruction to insert
i
)

Insert an instruction before instruction (handle) ih contained in this list.

public BranchHandle

Returns:

instruction handle of the first inserted instruction
insert
(InstructionHandle
where to insert to the instruction list
ih
,
InstructionBranch
Instruction to insert
i
)

Insert an instruction before instruction (handle) ih contained in this list.

public boolean
public Iterator<E>

Returns:

Enumeration that lists all instructions (handles)
iterator
()

public void
move(InstructionHandle
of moved block
start
,
InstructionHandle
of moved block
end
,
InstructionHandle
of moved block
target
)

Take all instructions (handles) from "start" to "end" and append them after the new location "target".

public void
move(InstructionHandle
moved instruction
ih
,
InstructionHandle
new location of moved instruction
target
)

Move a single instruction (handle) to a new location.

public void
redirectBranches(InstructionHandle
the old target instruction handle
old_target
,
InstructionHandle
the new target instruction handle
new_target
)

Redirect all references from old_target to new_target, i.e., update targets of branch instructions.

public void
redirectExceptionHandlers(CodeExceptionGen[]
array of exception handlers
exceptions
,
InstructionHandle
the old target instruction handle
old_target
,
InstructionHandle
the new target instruction handle
new_target
)

Redirect all references of exception handlers from old_target to new_target.

public void
redirectLocalVariables(LocalVariableGen[]
array of local variables
lg
,
InstructionHandle
the old target instruction handle
old_target
,
InstructionHandle
the new target instruction handle
new_target
)

Redirect all references of local variables from old_target to new_target.

private void
remove(InstructionHandle
where to start deleting (predecessor, exclusive)
prev
,
InstructionHandle
where to end deleting (successor, exclusive)
next
,
boolean careAboutLostTargeters)

Remove from instruction 'prev' to instruction 'next' both contained in this list.

public void
replaceConstantPool(ConstantPool old_cp, ConstantPool new_cp)

Replace all references to the old constant pool with references to the new constant pool

public void
public void
setPositions(boolean
Perform sanity checks, e.g. if all targeted instructions really belong to this list
check
)

Give all instructions their position number (offset in byte stream), i.e., make the list ready to be dumped.

public int

Returns:

length of list (Number of instructions, not bytes)
size
()

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public String

Returns:

String containing all instructions in this list.
toString
(boolean
toggle output format
verbose
)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

endback to summary
private InstructionHandle end
lengthback to summary
private int length
positionsback to summary
private int[] positions
startback to summary
private InstructionHandle start

Constructor Detail

InstructionListback to summary
public InstructionList()
InstructionListback to summary
public InstructionList(Instruction i)
InstructionListback to summary
public InstructionList(byte[] code)

Initialize instruction list from byte array.

Parameters
code:byte[]

byte array containing the instructions

Method Detail

appendback to summary
public InstructionHandle append(InstructionHandle appendTo, InstructionList appendee)

Append another list after instruction (handle) ih contained in this list. Consumes argument list, i.e., it becomes empty.

Parameters
appendTo:InstructionHandle

where to append the instruction list

appendee:InstructionList

Instruction list to append to this one

Returns:InstructionHandle

instruction handle pointing to the first appended instruction

appendback to summary
public InstructionHandle append(Instruction i, InstructionList il)

Append another list after instruction i contained in this list. Consumes argument list, i.e., it becomes empty.

Parameters
i:Instruction

where to append the instruction list

il:InstructionList

Instruction list to append to this one

Returns:InstructionHandle

instruction handle pointing to the first appended instruction

appendback to summary
public InstructionHandle append(InstructionList il)

Append another list to this one. Consumes argument list, i.e., it becomes empty.

Parameters
il:InstructionList

list to append to end of this list

Returns:InstructionHandle

instruction handle of the first appended instruction

appendback to summary
private void append(InstructionHandle ih)

Append an instruction to the end of this list.

Parameters
ih:InstructionHandle

instruction to append

appendback to summary
public InstructionHandle append(Instruction i)

Append an instruction to the end of this list.

Parameters
i:Instruction

instruction to append

Returns:InstructionHandle

instruction handle of the appended instruction

appendback to summary
public BranchHandle append(InstructionBranch i)

Append a branch instruction to the end of this list.

Parameters
i:InstructionBranch

branch instruction to append

Returns:BranchHandle

branch instruction handle of the appended instruction

appendback to summary
public InstructionHandle append(Instruction i, Instruction j)

Append a single instruction j after another instruction i, which must be in this list of course!

Parameters
i:Instruction

Instruction in list

j:Instruction

Instruction to append after i in list

Returns:InstructionHandle

instruction handle of the first appended instruction

appendback to summary
public InstructionHandle append(InstructionHandle ih, Instruction i)

Append an instruction after instruction (handle) ih contained in this list.

Parameters
ih:InstructionHandle

where to append the instruction list

i:Instruction

Instruction to append

Returns:InstructionHandle

instruction handle pointing to the first appended instruction

appendback to summary
public BranchHandle append(InstructionHandle ih, InstructionBranch i)

Append an instruction after instruction (handle) ih contained in this list.

Parameters
ih:InstructionHandle

where to append the instruction list

i:InstructionBranch

Instruction to append

Returns:BranchHandle

instruction handle pointing to the first appended instruction

appendDUPback to summary
public InstructionHandle appendDUP()
appendNOPback to summary
public InstructionHandle appendNOP()
appendPOPback to summary
public InstructionHandle appendPOP()
checkInstructionListback to summary
private void checkInstructionList()
clearback to summary
private void clear()
containsback to summary
public boolean contains(InstructionHandle i)
containsback to summary
public boolean contains(Instruction i)
copyback to summary
public InstructionList copy()
Returns:InstructionList

complete, i.e., deep copy of this list

deleteback to summary
public void delete(InstructionHandle ih) throws TargetLostException

Remove instruction from this list. The corresponding Instruction handles must not be reused!

Parameters
ih:InstructionHandle

instruction (handle) to remove

deleteback to summary
public void delete(InstructionHandle from, InstructionHandle to) throws TargetLostException

Remove instructions from instruction `from' to instruction `to' contained in this list. The user must ensure that `from' is an instruction before `to', or risk havoc. The corresponding Instruction handles must not be reused!

Parameters
from:InstructionHandle

where to start deleting (inclusive)

to:InstructionHandle

where to end deleting (inclusive)

deleteback to summary
public void delete(Instruction from, Instruction to) throws TargetLostException

Remove instructions from instruction `from' to instruction `to' contained in this list. The user must ensure that `from' is an instruction before `to', or risk havoc. The corresponding Instruction handles must not be reused!

Parameters
from:Instruction

where to start deleting (inclusive)

to:Instruction

where to end deleting (inclusive)

disposeback to summary
public void dispose()

Delete contents of list. Provides better memory utilization, because the system then may reuse the instruction handles. This method is typically called right after MethodGen.getMethod().

findHandleback to summary
public static InstructionHandle findHandle(InstructionHandle[] ihs, int[] pos, int count, int target)
findHandleback to summary
public static InstructionHandle findHandle(InstructionHandle[] ihs, int[] pos, int count, int target, boolean returnClosestIfNoExactMatch)

Find the target instruction (handle) that corresponds to the given target position (byte code offset).

Parameters
ihs:InstructionHandle[]

array of instruction handles, i.e. il.getInstructionHandles()

pos:int[]

array of positions corresponding to ihs, i.e. il.getInstructionPositions()

count:int

length of arrays

target:int

target position to search for

Returns:InstructionHandle

target position's instruction handle if available

findHandleback to summary
public InstructionHandle findHandle(int pos)

Get instruction handle for instruction at byte code position pos. This only works properly, if the list is freshly initialized from a byte array or setPositions() has been called before this method.

Parameters
pos:int

byte code position to search for

Returns:InstructionHandle

target position's instruction handle if available

findHandleback to summary
public InstructionHandle findHandle(int pos, InstructionHandle[] instructionArray)
findHandleback to summary
public InstructionHandle findHandle(int pos, InstructionHandle[] instructionArray, boolean useClosestApproximationIfNoExactFound)
findInstruction1back to summary
private InstructionHandle findInstruction1(Instruction i)

Search for given Instruction reference, start at beginning of list.

Parameters
i:Instruction

instruction to search for

Returns:InstructionHandle

instruction found on success, null otherwise

findInstruction2back to summary
private InstructionHandle findInstruction2(Instruction i)

Search for given Instruction reference, start at end of list

Parameters
i:Instruction

instruction to search for

Returns:InstructionHandle

instruction found on success, null otherwise

getByteCodeback to summary
public byte[] getByteCode()

When everything is finished, use this method to convert the instruction list into an array of bytes.

Returns:byte[]

the byte code ready to be dumped

getEndback to summary
public InstructionHandle getEnd()
Returns:InstructionHandle

end of list

getInstructionHandlesback to summary
public InstructionHandle[] getInstructionHandles()
Returns:InstructionHandle[]

array containing all instructions (handles)

getInstructionPositionsback to summary
public int[] getInstructionPositions()

Get positions (offsets) of all instructions in the list. This relies on that the list has been freshly created from an byte code array, or that setPositions() has been called. Otherwise this may be inaccurate.

Returns:int[]

array containing all instruction's offset in byte code

getInstructionsback to summary
public Instruction[] getInstructions()
Returns:Instruction[]

an array of instructions without target information for branch instructions.

getInstructionsAsArrayback to summary
public InstructionHandle[] getInstructionsAsArray()
getLengthback to summary
public int getLength()
Returns:int

length of list (Number of instructions, not bytes)

getStartback to summary
public InstructionHandle getStart()
Returns:InstructionHandle

start of list

insertback to summary
public InstructionHandle insert(InstructionHandle ih, InstructionList il)

Insert another list before Instruction handle ih contained in this list. Consumes argument list, i.e., it becomes empty.

Parameters
ih:InstructionHandle

where to append the instruction list

il:InstructionList

Instruction list to insert

Returns:InstructionHandle

instruction handle of the first inserted instruction

insertback to summary
public InstructionHandle insert(InstructionList il)

Insert another list.

Parameters
il:InstructionList

list to insert before start of this list

Returns:InstructionHandle

instruction handle of the first inserted instruction

insertback to summary
private void insert(InstructionHandle ih)

Insert an instruction at start of this list.

Parameters
ih:InstructionHandle

instruction to insert

insertback to summary
public InstructionHandle insert(Instruction i, InstructionList il)

Insert another list before Instruction i contained in this list. Consumes argument list, i.e., it becomes empty.

Parameters
i:Instruction

where to append the instruction list

il:InstructionList

Instruction list to insert

Returns:InstructionHandle

instruction handle pointing to the first inserted instruction, i.e., il.getStart()

insertback to summary
public InstructionHandle insert(Instruction i)

Insert an instruction at start of this list.

Parameters
i:Instruction

instruction to insert

Returns:InstructionHandle

instruction handle of the inserted instruction

insertback to summary
public BranchHandle insert(InstructionBranch i)

Insert a branch instruction at start of this list.

Parameters
i:InstructionBranch

branch instruction to insert

Returns:BranchHandle

branch instruction handle of the appended instruction

insertback to summary
public InstructionHandle insert(Instruction i, Instruction j)

Insert a single instruction j before another instruction i, which must be in this list of course!

Parameters
i:Instruction

Instruction in list

j:Instruction

Instruction to insert before i in list

Returns:InstructionHandle

instruction handle of the first inserted instruction

insertback to summary
public InstructionHandle insert(InstructionHandle ih, Instruction i)

Insert an instruction before instruction (handle) ih contained in this list.

Parameters
ih:InstructionHandle

where to insert to the instruction list

i:Instruction

Instruction to insert

Returns:InstructionHandle

instruction handle of the first inserted instruction

insertback to summary
public BranchHandle insert(InstructionHandle ih, InstructionBranch i)

Insert an instruction before instruction (handle) ih contained in this list.

Parameters
ih:InstructionHandle

where to insert to the instruction list

i:InstructionBranch

Instruction to insert

Returns:BranchHandle

instruction handle of the first inserted instruction

isEmptyback to summary
public boolean isEmpty()
iteratorback to summary
public Iterator<E> iterator()
Returns:Iterator<E>

Enumeration that lists all instructions (handles)

moveback to summary
public void move(InstructionHandle start, InstructionHandle end, InstructionHandle target)

Take all instructions (handles) from "start" to "end" and append them after the new location "target". Of course, "end" must be after "start" and target must not be located withing this range. If you want to move something to the start of the list use null as value for target.
Any instruction targeters pointing to handles within the block, keep their targets.

Parameters
start:InstructionHandle

of moved block

end:InstructionHandle

of moved block

target:InstructionHandle

of moved block

moveback to summary
public void move(InstructionHandle ih, InstructionHandle target)

Move a single instruction (handle) to a new location.

Parameters
ih:InstructionHandle

moved instruction

target:InstructionHandle

new location of moved instruction

redirectBranchesback to summary
public void redirectBranches(InstructionHandle old_target, InstructionHandle new_target)

Redirect all references from old_target to new_target, i.e., update targets of branch instructions.

Parameters
old_target:InstructionHandle

the old target instruction handle

new_target:InstructionHandle

the new target instruction handle

redirectExceptionHandlersback to summary
public void redirectExceptionHandlers(CodeExceptionGen[] exceptions, InstructionHandle old_target, InstructionHandle new_target)

Redirect all references of exception handlers from old_target to new_target.

Parameters
exceptions:CodeExceptionGen[]

array of exception handlers

old_target:InstructionHandle

the old target instruction handle

new_target:InstructionHandle

the new target instruction handle

See Also
MethodGen
redirectLocalVariablesback to summary
public void redirectLocalVariables(LocalVariableGen[] lg, InstructionHandle old_target, InstructionHandle new_target)

Redirect all references of local variables from old_target to new_target.

Parameters
lg:LocalVariableGen[]

array of local variables

old_target:InstructionHandle

the old target instruction handle

new_target:InstructionHandle

the new target instruction handle

See Also
MethodGen
removeback to summary
private void remove(InstructionHandle prev, InstructionHandle next, boolean careAboutLostTargeters) throws TargetLostException

Remove from instruction 'prev' to instruction 'next' both contained in this list. If careAboutLostTargeters is true then this method will throw a TargetLostException when one of the removed instruction handles is still being targeted.

Parameters
prev:InstructionHandle

where to start deleting (predecessor, exclusive)

next:InstructionHandle

where to end deleting (successor, exclusive)

replaceConstantPoolback to summary
public void replaceConstantPool(ConstantPool old_cp, ConstantPool new_cp)

Replace all references to the old constant pool with references to the new constant pool

setPositionsback to summary
public void setPositions()
setPositionsback to summary
public void setPositions(boolean check)

Give all instructions their position number (offset in byte stream), i.e., make the list ready to be dumped.

Parameters
check:boolean

Perform sanity checks, e.g. if all targeted instructions really belong to this list

sizeback to summary
public int size()
Returns:int

length of list (Number of instructions, not bytes)

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
toStringback to summary
public String toString(boolean verbose)
Parameters
verbose:boolean

toggle output format

Returns:String

String containing all instructions in this list.