org.apache.bcel.generic

## Class InstructionList

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

- All Implemented Interfaces:
    Iterable<InstructionHandle>

      public class InstructionList
      extends Object
      implements Iterable<InstructionHandle>

  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

    Constructors
    Constructor and Description
    `InstructionList()` Create (empty) instruction list.
    `InstructionList(BranchInstruction i)` Create instruction list containing one instruction.
    `InstructionList(byte[] code)` Initialize instruction list from byte array.
    `InstructionList(CompoundInstruction c)` Initialize list with (nonnull) compound instruction.
    `InstructionList(Instruction i)` Create instruction list containing one instruction.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addObserver(InstructionListObserver o)` Add observer for this object.
    `BranchHandle` | `append(BranchInstruction i)` Append a branch instruction to the end of this list.
    `InstructionHandle` | `append(CompoundInstruction c)` Append a compound instruction.
    `InstructionHandle` | `append(Instruction i)` Append an instruction to the end of this list.
    `InstructionHandle` | `append(Instruction i, CompoundInstruction c)` Append a compound instruction, after instruction i.
    `BranchHandle` | `append(InstructionHandle ih, BranchInstruction i)` Append an instruction after instruction (handle) ih contained in this list.
    `InstructionHandle` | `append(InstructionHandle ih, CompoundInstruction c)` Append a compound instruction.
    `InstructionHandle` | `append(InstructionHandle ih, Instruction i)` Append an instruction after instruction (handle) ih contained in this list.
    `InstructionHandle` | `append(InstructionHandle ih, InstructionList il)` 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.
    `boolean` | `contains(Instruction i)`
    `boolean` | `contains(InstructionHandle i)`
    `InstructionList` | `copy()`
    `void` | `delete(Instruction i)` Remove instruction from this list.
    `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)` 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.
    `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()`
    `int` | `getLength()`
    `InstructionHandle` | `getStart()`
    `BranchHandle` | `insert(BranchInstruction i)` Insert a branch instruction at start of this list.
    `InstructionHandle` | `insert(CompoundInstruction c)` Insert a compound instruction.
    `InstructionHandle` | `insert(Instruction i)` Insert an instruction at start of this list.
    `InstructionHandle` | `insert(Instruction i, CompoundInstruction c)` Insert a compound instruction before instruction i.
    `BranchHandle` | `insert(InstructionHandle ih, BranchInstruction i)` Insert an instruction before instruction (handle) ih contained in this list.
    `InstructionHandle` | `insert(InstructionHandle ih, CompoundInstruction c)` Insert a compound instruction.
    `InstructionHandle` | `insert(InstructionHandle ih, Instruction 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()` Test for empty list.
    `Iterator<InstructionHandle>` | `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 oldTarget, InstructionHandle newTarget)` Redirect all references from oldTarget to newTarget, i.e., update targets of branch instructions.
    `void` | `redirectExceptionHandlers(CodeExceptionGen[] exceptions, InstructionHandle oldTarget, InstructionHandle newTarget)` Redirect all references of exception handlers from oldTarget to newTarget.
    `void` | `redirectLocalVariables(LocalVariableGen[] lg, InstructionHandle oldTarget, InstructionHandle newTarget)` Redirect all references of local variables from oldTarget to newTarget.
    `void` | `removeObserver(InstructionListObserver o)` Remove observer for this object.
    `void` | `replaceConstantPool(ConstantPoolGen oldCp, ConstantPoolGen newCp)` 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()`
    `String` | `toString()`
    `String` | `toString(boolean verbose)`
    `void` | `update()` Call notify() method on all observers.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### InstructionList

          public InstructionList()

      Create (empty) instruction list.

    - #### InstructionList

          public InstructionList(BranchInstruction i)

      Create instruction list containing one instruction.
      Parameters:
        `i` - initial instruction

    - #### InstructionList

          public InstructionList(byte[] code)

      Initialize instruction list from byte array.
      Parameters:
        `code` - byte array containing the instructions

    - #### 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(Instruction i)

      Create instruction list containing one instruction.
      Parameters:
        `i` - initial instruction

  - ### Method Detail

    - #### 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

    - #### addObserver

          public void addObserver(InstructionListObserver o)

      Add observer for this object.

    - #### 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(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(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 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(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,
                                          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 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

    - #### 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 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(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

    - #### contains

          public boolean contains(Instruction i)

    - #### contains

          public boolean contains(InstructionHandle i)

    - #### copy

          public InstructionList copy()

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

    - #### delete

          public void delete(Instruction i)
                      throws TargetLostException

      Remove instruction from this list. The corresponding Instruction handles must not be reused!
      Parameters:
        `i` - instruction to remove
      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`

    - #### 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`

    - #### 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()`.

    - #### 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 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(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(Instruction i)

      Insert an instruction at start of this list.
      Parameters:
        `i` - instruction to insert
      Returns:
        instruction handle of the 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(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,
                                          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 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

    - #### 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 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,
                                          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

    - #### isEmpty

          public boolean isEmpty()

      Test for empty list.

    - #### iterator

          public Iterator<InstructionHandle> iterator()

      Specified by:
        `iterator` in interface `Iterable<InstructionHandle>`
      Returns:
        iterator that lists all instructions (handles)

    - #### 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

    - #### 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

    - #### redirectBranches

          public void redirectBranches(InstructionHandle oldTarget,
                                       InstructionHandle newTarget)

      Redirect all references from oldTarget to newTarget, i.e., update targets of branch instructions.
      Parameters:
        `oldTarget` - the old target instruction handle
        `newTarget` - the new target instruction handle

    - #### redirectExceptionHandlers

          public void redirectExceptionHandlers(CodeExceptionGen[] exceptions,
                                                InstructionHandle oldTarget,
                                                InstructionHandle newTarget)

      Redirect all references of exception handlers from oldTarget to newTarget.
      Parameters:
        `exceptions` - array of exception handlers
        `oldTarget` - the old target instruction handle
        `newTarget` - the new target instruction handle
      See Also:
        `MethodGen`

    - #### redirectLocalVariables

          public void redirectLocalVariables(LocalVariableGen[] lg,
                                             InstructionHandle oldTarget,
                                             InstructionHandle newTarget)

      Redirect all references of local variables from oldTarget to newTarget.
      Parameters:
        `lg` - array of local variables
        `oldTarget` - the old target instruction handle
        `newTarget` - the new target instruction handle
      See Also:
        `MethodGen`

    - #### removeObserver

          public void removeObserver(InstructionListObserver o)

      Remove observer for this object.

    - #### replaceConstantPool

          public void replaceConstantPool(ConstantPoolGen oldCp,
                                          ConstantPoolGen newCp)

      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()

      Overrides:
        `toString` in class `Object`

    - #### 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.

Copyright © 2004–2022 The Apache Software Foundation. All rights reserved.