InstructionList

java.lang.Object
- org.aspectj.apache.bcel.generic.InstructionList

All Implemented Interfaces:

java.io.Serializable
```
public class InstructionList
extends java.lang.Object
implements java.io.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, Serialized Form

Constructor Summary

Constructors
Constructor and Description

InstructionList()

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

InstructionList(Instruction i)

Constructors
Constructor and Description
`InstructionList()`
`InstructionList(byte[] code)` Initialize instruction list from byte array.
`InstructionList(Instruction i)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`InstructionHandle`	`append(Instruction i)` Append an instruction to the end of this list.
`BranchHandle`	`append(InstructionBranch i)` Append a branch instruction to the end of this list.
`InstructionHandle`	`append(InstructionHandle ih, Instruction i)` Append an instruction after instruction (handle) ih contained in this list.
`BranchHandle`	`append(InstructionHandle ih, InstructionBranch i)` Append an instruction after instruction (handle) ih contained in this list.
`InstructionHandle`	`append(InstructionHandle appendTo, InstructionList appendee)` Append another list after instruction (handle) ih contained in this list.
`InstructionHandle`	`append(Instruction i, Instruction j)` Append a single instruction j after another instruction i, which must be in this list of course!
`InstructionHandle`	`append(Instruction i, InstructionList il)` Append another list after instruction i contained in this list.
`InstructionHandle`	`append(InstructionList il)` Append another list to this one.
`InstructionHandle`	`appendDUP()`
`InstructionHandle`	`appendNOP()`
`InstructionHandle`	`appendPOP()`
`boolean`	`contains(Instruction i)`
`boolean`	`contains(InstructionHandle i)`
`InstructionList`	`copy()`
`void`	`delete(InstructionHandle ih)` Remove instruction from this list.
`void`	`delete(InstructionHandle from, InstructionHandle to)` Remove instructions from instruction `from' to instruction `to' contained in this list.
`void`	`delete(Instruction from, Instruction to)` Remove instructions from instruction `from' to instruction `to' contained in this list.
`void`	`dispose()` Delete contents of list.
`static InstructionHandle`	`findHandle(InstructionHandle[] ihs, int[] pos, int count, int target)`
`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).
`InstructionHandle`	`findHandle(int pos)` Get instruction handle for instruction at byte code position pos.
`InstructionHandle`	`findHandle(int pos, InstructionHandle[] instructionArray)`
`InstructionHandle`	`findHandle(int pos, InstructionHandle[] instructionArray, boolean useClosestApproximationIfNoExactFound)`
`byte[]`	`getByteCode()` When everything is finished, use this method to convert the instruction list into an array of bytes.
`InstructionHandle`	`getEnd()`
`InstructionHandle[]`	`getInstructionHandles()`
`int[]`	`getInstructionPositions()` Get positions (offsets) of all instructions in the list.
`Instruction[]`	`getInstructions()`
`InstructionHandle[]`	`getInstructionsAsArray()`
`int`	`getLength()`
`InstructionHandle`	`getStart()`
`InstructionHandle`	`insert(Instruction i)` Insert an instruction at start of this list.
`BranchHandle`	`insert(InstructionBranch i)` Insert a branch instruction at start of this list.
`InstructionHandle`	`insert(InstructionHandle ih, Instruction i)` Insert an instruction before instruction (handle) ih contained in this list.
`BranchHandle`	`insert(InstructionHandle ih, InstructionBranch i)` Insert an instruction before instruction (handle) ih contained in this list.
`InstructionHandle`	`insert(InstructionHandle ih, InstructionList il)` Insert another list before Instruction handle ih contained in this list.
`InstructionHandle`	`insert(Instruction i, Instruction j)` Insert a single instruction j before another instruction i, which must be in this list of course!
`InstructionHandle`	`insert(Instruction i, InstructionList il)` Insert another list before Instruction i contained in this list.
`InstructionHandle`	`insert(InstructionList il)` Insert another list.
`boolean`	`isEmpty()`
`java.util.Iterator`	`iterator()`
`void`	`move(InstructionHandle ih, InstructionHandle target)` Move a single instruction (handle) to a new location.
`void`	`move(InstructionHandle start, InstructionHandle end, InstructionHandle target)` Take all instructions (handles) from "start" to "end" and append them after the new location "target".
`void`	`redirectBranches(InstructionHandle old_target, InstructionHandle new_target)` Redirect all references from old_target to new_target, i.e., update targets of branch instructions.
`void`	`redirectExceptionHandlers(CodeExceptionGen[] exceptions, InstructionHandle old_target, InstructionHandle new_target)` Redirect all references of exception handlers from old_target to new_target.
`void`	`redirectLocalVariables(LocalVariableGen[] lg, InstructionHandle old_target, InstructionHandle new_target)` Redirect all references of local variables from old_target to new_target.
`void`	`replaceConstantPool(ConstantPool old_cp, ConstantPool new_cp)` Replace all references to the old constant pool with references to the new constant pool
`void`	`setPositions()`
`void`	`setPositions(boolean check)` Give all instructions their position number (offset in byte stream), i.e., make the list ready to be dumped.
`int`	`size()`
`java.lang.String`	`toString()`
`java.lang.String`	`toString(boolean verbose)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - InstructionList
```
public InstructionList()
```
  - InstructionList
```
public InstructionList(Instruction i)
```
  - InstructionList
```
public InstructionList(byte[] code)
```
    Initialize instruction list from byte array.
    
    Parameters:
    
    code - byte array containing the instructions
- Method Detail
  - isEmpty
```
public boolean isEmpty()
```
  - findHandle
```
public static InstructionHandle findHandle(InstructionHandle[] ihs,
                                           int[] pos,
                                           int count,
                                           int target)
```
  - findHandle
```
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 - 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
  - getInstructionsAsArray
```
public InstructionHandle[] getInstructionsAsArray()
```
  - findHandle
```
public InstructionHandle findHandle(int pos,
                                    InstructionHandle[] instructionArray)
```
  - findHandle
```
public InstructionHandle findHandle(int pos,
                                    InstructionHandle[] instructionArray,
                                    boolean useClosestApproximationIfNoExactFound)
```
  - append
```
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 - where to append the instruction list
    
    appendee - 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
  - appendDUP
```
public InstructionHandle appendDUP()
```
  - appendNOP
```
public InstructionHandle appendNOP()
```
  - appendPOP
```
public InstructionHandle appendPOP()
```
  - append
```
public BranchHandle append(InstructionBranch 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(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,
                           InstructionBranch 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
  - 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:
    
    i - 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(InstructionBranch 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(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 BranchHandle insert(InstructionHandle ih,
                           InstructionBranch 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
  - 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
  - delete
```
public void delete(InstructionHandle ih)
            throws TargetLostException
```
    Remove instruction from this list. The corresponding Instruction handles must not be reused!
    
    Parameters:
    
    ih - instruction (handle) to remove
    
    Throws:
    
    TargetLostException
  - delete
```
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 - where to start deleting (inclusive)
    
    to - where to end deleting (inclusive)
    
    Throws:
    
    TargetLostException
  - delete
```
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 - where to start deleting (inclusive)
    
    to - where to end deleting (inclusive)
    
    Throws:
    
    TargetLostException
  - contains
```
public boolean contains(InstructionHandle i)
```
  - contains
```
public boolean contains(Instruction i)
```
  - 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
  - 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
  - getInstructions
```
public Instruction[] getInstructions()
```
    Returns:
    
    an array of instructions without target information for branch instructions.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toString
```
public java.lang.String toString(boolean verbose)
```
    Parameters:
    
    verbose - toggle output format
    
    Returns:
    
    String containing all instructions in this list.
  - iterator
```
public java.util.Iterator iterator()
```
    Returns:
    
    Enumeration that lists all instructions (handles)
  - 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
  - copy
```
public InstructionList copy()
```
    Returns:
    
    complete, i.e., deep copy of this list
  - replaceConstantPool
```
public void replaceConstantPool(ConstantPool old_cp,
                                ConstantPool new_cp)
```
    Replace all references to the old constant pool with references to the new constant pool
  - dispose
```
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().
  - getStart
```
public InstructionHandle getStart()
```
    Returns:
    
    start of list
  - getEnd
```
public InstructionHandle getEnd()
```
    Returns:
    
    end of list
  - getLength
```
public int getLength()
```
    Returns:
    
    length of list (Number of instructions, not bytes)
  - size
```
public int size()
```
    Returns:
    
    length of list (Number of instructions, not bytes)
  - 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
  - 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
  - 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

Class InstructionList

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

InstructionList

InstructionList

InstructionList

Method Detail

isEmpty

findHandle

findHandle

findHandle

getInstructionsAsArray

findHandle

findHandle

append

append

append

append

appendDUP

appendNOP

appendPOP

append

append

append

append

insert

insert

insert

insert

insert

insert

insert

insert

move

move

delete

delete

delete

contains

contains

setPositions

setPositions

getByteCode

getInstructions

toString

toString

iterator

getInstructionHandles

getInstructionPositions

copy

replaceConstantPool

dispose

getStart

getEnd

getLength

size

redirectBranches

redirectLocalVariables

redirectExceptionHandlers