org.apache.bcel.generic

Class InstructionList

public class InstructionList extends Object implements Serializable

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.

See Also: Instruction InstructionHandle BranchHandle

Constructor Summary
InstructionList()
Create (empty) instruction list.
InstructionList(Instruction i)
Create instruction list containing one instruction.
InstructionList(BranchInstruction i)
Create instruction list containing one instruction.
InstructionList(CompoundInstruction c)
Initialize list with (nonnull) compound instruction.
InstructionList(byte[] code)
Initialize instruction list from byte array.
Method Summary
voidaddObserver(InstructionListObserver o)
Add observer for this object.
InstructionHandleappend(InstructionHandle ih, InstructionList il)
Append another list after instruction (handle) ih contained in this list.
InstructionHandleappend(Instruction i, InstructionList il)
Append another list after instruction i contained in this list.
InstructionHandleappend(InstructionList il)
Append another list to this one.
InstructionHandleappend(Instruction i)
Append an instruction to the end of this list.
BranchHandleappend(BranchInstruction i)
Append a branch instruction to the end of this list.
InstructionHandleappend(Instruction i, Instruction j)
Append a single instruction j after another instruction i, which must be in this list of course!
InstructionHandleappend(Instruction i, CompoundInstruction c)
Append a compound instruction, after instruction i.
InstructionHandleappend(CompoundInstruction c)
Append a compound instruction.
InstructionHandleappend(InstructionHandle ih, CompoundInstruction c)
Append a compound instruction.
InstructionHandleappend(InstructionHandle ih, Instruction i)
Append an instruction after instruction (handle) ih contained in this list.
BranchHandleappend(InstructionHandle ih, BranchInstruction i)
Append an instruction after instruction (handle) ih contained in this list.
booleancontains(InstructionHandle i)
booleancontains(Instruction i)
InstructionListcopy()
voiddelete(InstructionHandle ih)
Remove instruction from this list.
voiddelete(Instruction i)
Remove instruction from this list.
voiddelete(InstructionHandle from, InstructionHandle to)
Remove instructions from instruction `from' to instruction `to' contained in this list.
voiddelete(Instruction from, Instruction to)
Remove instructions from instruction `from' to instruction `to' contained in this list.
voiddispose()
Delete contents of list.
static InstructionHandlefindHandle(InstructionHandle[] ihs, int[] pos, int count, int target)
Find the target instruction (handle) that corresponds to the given target position (byte code offset).
InstructionHandlefindHandle(int pos)
Get instruction handle for instruction at byte code position pos.
byte[]getByteCode()
When everything is finished, use this method to convert the instruction list into an array of bytes.
InstructionHandlegetEnd()
InstructionHandle[]getInstructionHandles()
int[]getInstructionPositions()
Get positions (offsets) of all instructions in the list.
Instruction[]getInstructions()
intgetLength()
InstructionHandlegetStart()
InstructionHandleinsert(InstructionHandle ih, InstructionList il)
Insert another list before Instruction handle ih contained in this list.
InstructionHandleinsert(InstructionList il)
Insert another list.
InstructionHandleinsert(Instruction i, InstructionList il)
Insert another list before Instruction i contained in this list.
InstructionHandleinsert(Instruction i)
Insert an instruction at start of this list.
BranchHandleinsert(BranchInstruction i)
Insert a branch instruction at start of this list.
InstructionHandleinsert(Instruction i, Instruction j)
Insert a single instruction j before another instruction i, which must be in this list of course!
InstructionHandleinsert(Instruction i, CompoundInstruction c)
Insert a compound instruction before instruction i.
InstructionHandleinsert(CompoundInstruction c)
Insert a compound instruction.
InstructionHandleinsert(InstructionHandle ih, Instruction i)
Insert an instruction before instruction (handle) ih contained in this list.
InstructionHandleinsert(InstructionHandle ih, CompoundInstruction c)
Insert a compound instruction.
BranchHandleinsert(InstructionHandle ih, BranchInstruction i)
Insert an instruction before instruction (handle) ih contained in this list.
booleanisEmpty()
Test for empty list.
Iteratoriterator()
voidmove(InstructionHandle start, InstructionHandle end, InstructionHandle target)
Take all instructions (handles) from "start" to "end" and append them after the new location "target".
voidmove(InstructionHandle ih, InstructionHandle target)
Move a single instruction (handle) to a new location.
voidredirectBranches(InstructionHandle old_target, InstructionHandle new_target)
Redirect all references from old_target to new_target, i.e., update targets of branch instructions.
voidredirectExceptionHandlers(CodeExceptionGen[] exceptions, InstructionHandle old_target, InstructionHandle new_target)
Redirect all references of exception handlers from old_target to new_target.
voidredirectLocalVariables(LocalVariableGen[] lg, InstructionHandle old_target, InstructionHandle new_target)
Redirect all references of local variables from old_target to new_target.
voidremoveObserver(InstructionListObserver o)
Remove observer for this object.
voidreplaceConstantPool(ConstantPoolGen old_cp, ConstantPoolGen new_cp)
Replace all references to the old constant pool with references to the new constant pool
voidsetPositions()
voidsetPositions(boolean check)
Give all instructions their position number (offset in byte stream), i.e., make the list ready to be dumped.
intsize()
StringtoString()
StringtoString(boolean verbose)
voidupdate()
Call notify() method on all observers.

Constructor Detail

InstructionList

public InstructionList()
Create (empty) instruction list.

InstructionList

public InstructionList(Instruction i)
Create instruction list containing one instruction.

Parameters: i initial instruction

InstructionList

public InstructionList(BranchInstruction i)
Create instruction list containing one instruction.

Parameters: i initial instruction

InstructionList

public InstructionList(CompoundInstruction c)
Initialize list with (nonnull) compound instruction. Consumes argument list, i.e., it becomes empty.

Parameters: c compound instruction (list)

InstructionList

public InstructionList(byte[] code)
Initialize instruction list from byte array.

Parameters: code byte array containing the instructions

Method Detail

addObserver

public void addObserver(InstructionListObserver o)
Add observer for this object.

append

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

Parameters: ih where to append the instruction list il Instruction list to append to this one

Returns: instruction handle pointing to the first appended instruction

append

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 where to append the instruction list il Instruction list to append to this one

Returns: instruction handle pointing to the first appended instruction

append

public InstructionHandle append(InstructionList il)
Append another list to this one. Consumes argument list, i.e., it becomes empty.

Parameters: il list to append to end of this list

Returns: instruction handle of the first appended instruction

append

public InstructionHandle append(Instruction i)
Append an instruction to the end of this list.

Parameters: i instruction to append

Returns: instruction handle of the appended instruction

append

public BranchHandle append(BranchInstruction i)
Append a branch instruction to the end of this list.

Parameters: i branch instruction to append

Returns: branch instruction handle of the appended instruction

append

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 in list j Instruction to append after i in list

Returns: instruction handle of the first appended instruction

append

public InstructionHandle append(Instruction i, CompoundInstruction c)
Append a compound instruction, after instruction i.

Parameters: i Instruction in list c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first appended instruction

append

public InstructionHandle append(CompoundInstruction c)
Append a compound instruction.

Parameters: c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first appended instruction

append

public InstructionHandle append(InstructionHandle ih, CompoundInstruction c)
Append a compound instruction.

Parameters: ih where to append the instruction list c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first appended instruction

append

public InstructionHandle append(InstructionHandle ih, Instruction i)
Append an instruction after instruction (handle) ih contained in this list.

Parameters: ih where to append the instruction list i Instruction to append

Returns: instruction handle pointing to the first appended instruction

append

public BranchHandle append(InstructionHandle ih, BranchInstruction i)
Append an instruction after instruction (handle) ih contained in this list.

Parameters: ih where to append the instruction list i Instruction to append

Returns: instruction handle pointing to the first appended instruction

contains

public boolean contains(InstructionHandle i)

contains

public boolean contains(Instruction i)

copy

public InstructionList copy()

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

delete

public void delete(InstructionHandle ih)
Remove instruction from this list. The corresponding Instruction handles must not be reused!

Parameters: ih instruction (handle) to remove

delete

public void delete(Instruction i)
Remove instruction from this list. The corresponding Instruction handles must not be reused!

Parameters: i instruction to remove

delete

public void delete(InstructionHandle from, InstructionHandle to)
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 where to start deleting (inclusive) to where to end deleting (inclusive)

delete

public void delete(Instruction from, Instruction to)
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 where to start deleting (inclusive) to where to end deleting (inclusive)

dispose

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

findHandle

public static InstructionHandle findHandle(InstructionHandle[] ihs, int[] pos, int count, int target)
Find the target instruction (handle) that corresponds to the given target position (byte code offset).

Parameters: ihs array of instruction handles, i.e. il.getInstructionHandles() pos array of positions corresponding to ihs, i.e. il.getInstructionPositions() count length of arrays target target position to search for

Returns: target position's instruction handle if available

findHandle

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 byte code position to search for

Returns: target position's instruction handle if available

getByteCode

public byte[] getByteCode()
When everything is finished, use this method to convert the instruction list into an array of bytes.

Returns: the byte code ready to be dumped

getEnd

public InstructionHandle getEnd()

Returns: end of list

getInstructionHandles

public InstructionHandle[] getInstructionHandles()

Returns: array containing all instructions (handles)

getInstructionPositions

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: array containing all instruction's offset in byte code

getInstructions

public Instruction[] getInstructions()

Returns: an array of instructions without target information for branch instructions.

getLength

public int getLength()

Returns: length of list (Number of instructions, not bytes)

getStart

public InstructionHandle getStart()

Returns: start of list

insert

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 where to append the instruction list il Instruction list to insert

Returns: instruction handle of the first inserted instruction

insert

public InstructionHandle insert(InstructionList il)
Insert another list.

Parameters: il list to insert before start of this list

Returns: instruction handle of the first inserted instruction

insert

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 where to append the instruction list il Instruction list to insert

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

insert

public InstructionHandle insert(Instruction i)
Insert an instruction at start of this list.

Parameters: i instruction to insert

Returns: instruction handle of the inserted instruction

insert

public BranchHandle insert(BranchInstruction i)
Insert a branch instruction at start of this list.

Parameters: i branch instruction to insert

Returns: branch instruction handle of the appended instruction

insert

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 in list j Instruction to insert before i in list

Returns: instruction handle of the first inserted instruction

insert

public InstructionHandle insert(Instruction i, CompoundInstruction c)
Insert a compound instruction before instruction i.

Parameters: i Instruction in list c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first inserted instruction

insert

public InstructionHandle insert(CompoundInstruction c)
Insert a compound instruction.

Parameters: c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first inserted instruction

insert

public InstructionHandle insert(InstructionHandle ih, Instruction i)
Insert an instruction before instruction (handle) ih contained in this list.

Parameters: ih where to insert to the instruction list i Instruction to insert

Returns: instruction handle of the first inserted instruction

insert

public InstructionHandle insert(InstructionHandle ih, CompoundInstruction c)
Insert a compound instruction.

Parameters: ih where to insert the instruction list c The composite instruction (containing an InstructionList)

Returns: instruction handle of the first inserted instruction

insert

public BranchHandle insert(InstructionHandle ih, BranchInstruction i)
Insert an instruction before instruction (handle) ih contained in this list.

Parameters: ih where to insert to the instruction list i Instruction to insert

Returns: instruction handle of the first inserted instruction

isEmpty

public boolean isEmpty()
Test for empty list.

iterator

public Iterator iterator()

Returns: Enumeration that lists all instructions (handles)

move

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 of moved block end of moved block target of moved block

move

public void move(InstructionHandle ih, InstructionHandle target)
Move a single instruction (handle) to a new location.

Parameters: ih moved instruction target new location of moved instruction

redirectBranches

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 the old target instruction handle new_target the new target instruction handle

redirectExceptionHandlers

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 array of exception handlers old_target the old target instruction handle new_target the new target instruction handle

See Also: MethodGen

redirectLocalVariables

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 array of local variables old_target the old target instruction handle new_target the new target instruction handle

See Also: MethodGen

removeObserver

public void removeObserver(InstructionListObserver o)
Remove observer for this object.

replaceConstantPool

public void replaceConstantPool(ConstantPoolGen old_cp, ConstantPoolGen new_cp)
Replace all references to the old constant pool with references to the new constant pool

setPositions

public void setPositions()

setPositions

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 Perform sanity checks, e.g. if all targeted instructions really belong to this list

size

public int size()

Returns: length of list (Number of instructions, not bytes)

toString

public String toString()

toString

public String toString(boolean verbose)

Parameters: verbose toggle output format

Returns: String containing all instructions in this list.

update

public void update()
Call notify() method on all observers. This method is not called automatically whenever the state has changed, but has to be called by the user after he has finished editing the object.