org.apache.bcel.generic

## Class InstructionHandle

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

- Direct Known Subclasses:
    BranchHandle

      public class InstructionHandle
      extends Object

  Instances of this class give users a handle to the instructions contained in an InstructionList. Instruction objects may be used more than once within a list, this is useful because it saves memory and may be much faster. Within an InstructionList an InstructionHandle object is wrapped around all instructions, i.e., it implements a cell in a doubly-linked list. From the outside only the next and the previous instruction (handle) are accessible. One can traverse the list via an Enumeration returned by InstructionList.elements().
  See Also:
    `Instruction`, `BranchHandle`, `InstructionList`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static InstructionHandle[]` | `EMPTY_ARRAY` Empty array.
    `protected int` | `i_position` Deprecated. (since 6.0) will be made private; do not access directly, use getter/setter

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `InstructionHandle(Instruction i)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `accept(Visitor v)` Convenience method, simply calls accept() on the contained instruction.
    `void` | `addAttribute(Object key, Object attr)` Add an attribute to an instruction handle.
    `protected void` | `addHandle()` Deprecated. Does nothing as of 6.3.1.
    `void` | `addTargeter(InstructionTargeter t)` Denote this handle is being referenced by t.
    `Object` | `getAttribute(Object key)` Get attribute of an instruction handle.
    `Collection<Object>` | `getAttributes()`
    `Instruction` | `getInstruction()`
    `InstructionHandle` | `getNext()`
    `int` | `getPosition()`
    `InstructionHandle` | `getPrev()`
    `InstructionTargeter[]` | `getTargeters()`
    `boolean` | `hasTargeters()`
    `void` | `removeAllTargeters()` Remove all targeters, if any.
    `void` | `removeAttribute(Object key)` Delete an attribute of an instruction handle.
    `void` | `removeTargeter(InstructionTargeter t)` Denote this handle isn't referenced anymore by t.
    `void` | `setInstruction(Instruction i)` Replace current instruction contained in this handle.
    `Instruction` | `swapInstruction(Instruction i)` Temporarily swap the current instruction, without disturbing anything.
    `String` | `toString()`
    `String` | `toString(boolean verbose)`
    `protected int` | `updatePosition(int offset, int maxOffset)` Called by InstructionList.setPositions when setting the position for every instruction.

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

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

- - ### Field Detail

    - #### EMPTY_ARRAY

          public static final InstructionHandle[] EMPTY_ARRAY

      Empty array.
      Since:
        6.6.0

    - #### i_position

          @Deprecated
          protected int i_position

      Deprecated. (since 6.0) will be made private; do not access directly, use getter/setter

  - ### Constructor Detail

    - #### InstructionHandle

          protected InstructionHandle(Instruction i)

  - ### Method Detail

    - #### accept

          public void accept(Visitor v)

      Convenience method, simply calls accept() on the contained instruction.
      Parameters:
        `v` - Visitor object

    - #### addAttribute

          public void addAttribute(Object key,
                                   Object attr)

      Add an attribute to an instruction handle.
      Parameters:
        `key` - the key object to store/retrieve the attribute
        `attr` - the attribute to associate with this handle

    - #### addHandle

          @Deprecated
          protected void addHandle()

      Deprecated. Does nothing as of 6.3.1.
      Does nothing.

    - #### addTargeter

          public void addTargeter(InstructionTargeter t)

      Denote this handle is being referenced by t.

    - #### getAttribute

          public Object getAttribute(Object key)

      Get attribute of an instruction handle.
      Parameters:
        `key` - the key object to store/retrieve the attribute

    - #### getAttributes

          public Collection<Object> getAttributes()

      Returns:
        all attributes associated with this handle

    - #### getInstruction

          public final Instruction getInstruction()

    - #### getNext

          public final InstructionHandle getNext()

    - #### getPosition

          public int getPosition()

      Returns:
        the position, i.e., the byte code offset of the contained instruction. This is accurate only after InstructionList.setPositions() has been called.

    - #### getPrev

          public final InstructionHandle getPrev()

    - #### getTargeters

          public InstructionTargeter[] getTargeters()

      Returns:
        null, if there are no targeters

    - #### hasTargeters

          public boolean hasTargeters()

    - #### removeAllTargeters

          public void removeAllTargeters()

      Remove all targeters, if any.

    - #### removeAttribute

          public void removeAttribute(Object key)

      Delete an attribute of an instruction handle.
      Parameters:
        `key` - the key object to retrieve the attribute

    - #### removeTargeter

          public void removeTargeter(InstructionTargeter t)

      Denote this handle isn't referenced anymore by t.

    - #### setInstruction

          public void setInstruction(Instruction i)

      Replace current instruction contained in this handle. Old instruction is disposed using Instruction.dispose().

    - #### swapInstruction

          public Instruction swapInstruction(Instruction i)

      Temporarily swap the current instruction, without disturbing anything. Meant to be used by a debugger, implementing breakpoints. Current instruction is returned.

      Warning: if this is used on a BranchHandle then some methods such as getPosition() will still refer to the original cached instruction, whereas other BH methods may affect the cache and the replacement instruction.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of the contained instruction.

    - #### toString

          public String toString(boolean verbose)

      Returns:
        a (verbose) string representation of the contained instruction.

    - #### updatePosition

          protected int updatePosition(int offset,
                                       int maxOffset)

      Called by InstructionList.setPositions when setting the position for every instruction. In the presence of variable length instructions 'setPositions()' performs multiple passes over the instruction list to calculate the correct (byte) positions and offsets by calling this function.
      Parameters:
        `offset` - additional offset caused by preceding (variable length) instructions
        `maxOffset` - the maximum offset that may be caused by these instructions
      Returns:
        additional offset caused by possible change of this instruction's length

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