# 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, that is, 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
  Description
  `static final 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
  Description
  `protected`
  `InstructionHandle(Instruction i)`
  Constructs an InstructionHandle.

- ## Method Summary

  Modifier and Type
  Method
  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)`
  Gets attribute of an instruction handle.
  `Collection<Object>`
  `getAttributes()`
  Gets all attributes associated with this handle.
  `final Instruction`
  `getInstruction()`
  Gets the instruction.
  `final InstructionHandle`
  `getNext()`
  Gets the next instruction handle.
  `int`
  `getPosition()`
  Gets the position.
  `final InstructionHandle`
  `getPrev()`
  Gets the previous instruction handle.
  `InstructionTargeter[]`
  `getTargeters()`
  Gets the targeters.
  `boolean`
  `hasTargeters()`
  Checks if this handle has targeters.
  `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()`
  Gets a string representation of the contained instruction.
  `String`
  `toString(boolean verbose)`
  Gets a verbose string representation of the contained instruction.
  `protected int`
  `updatePosition(int offset, int maxOffset)`
  Called by InstructionList.setPositions when setting the position for every instruction.

  ### Methods inherited from class Object

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

- ## Field Details

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

  - ### InstructionHandle

    protected InstructionHandle(Instruction i)
    Constructs an InstructionHandle.
    Parameters:
      `i` - the instruction.

- ## Method Details

  - ### 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.
    Parameters:
      `t` - the instruction targeter.

  - ### getAttribute

    public Object getAttribute(Object key)
    Gets attribute of an instruction handle.
    Parameters:
      `key` - the key object to store/retrieve the attribute.
    Returns:
      the attribute value.

  - ### getAttributes

    public Collection<Object> getAttributes()
    Gets all attributes associated with this handle.
    Returns:
      all attributes associated with this handle.

  - ### getInstruction

    public final Instruction getInstruction()
    Gets the instruction.
    Returns:
      the instruction.

  - ### getNext

    public final InstructionHandle getNext()
    Gets the next instruction handle.
    Returns:
      the next instruction handle.

  - ### getPosition

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

  - ### getPrev

    public final InstructionHandle getPrev()
    Gets the previous instruction handle.
    Returns:
      the previous instruction handle.

  - ### getTargeters

    public InstructionTargeter[] getTargeters()
    Gets the targeters.
    Returns:
      null, if there are no targeters.

  - ### hasTargeters

    public boolean hasTargeters()
    Checks if this handle has targeters.
    Returns:
      true if this handle has targeters, false otherwise.

  - ### 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.
    Parameters:
      `t` - the instruction targeter.

  - ### setInstruction

    public void setInstruction(Instruction i)
    Replace current instruction contained in this handle. Old instruction is disposed using Instruction.dispose().
    Parameters:
      `i` - the new instruction.

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

    Parameters:
      `i` - the replacement instruction.
    Returns:
      the old instruction.

  - ### toString

    public String toString()
    Gets a string representation of the contained instruction.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of the contained instruction.

  - ### toString

    public String toString(boolean verbose)
    Gets a verbose string representation of the contained instruction.
    Parameters:
      `verbose` - whether to be 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.