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 max_offset)` 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 max_offset)

      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
        `max_offset` - 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.