Top Description Fields Constructors Methods
org.apache.bcel.generic

public Class InstructionHandle

extends Object
Class Inheritance
Known Direct Subclasses
org.apache.bcel.generic.BranchHandle
Imports
java.util.Collection, .HashMap, .HashSet, .Map, .Set, org.apache.bcel.classfile.Utility
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

Modifier and TypeField and Description
private Map<Object, Object>
attributes

public static final InstructionHandle[]
EMPTY_ARRAY

Empty array.

pack-priv static final InstructionTargeter[]
EMPTY_INSTRUCTION_TARGETER_ARRAY

Empty array.

protected int
i_position

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

private InstructionHandle
next

private InstructionHandle
prev

private Set<InstructionTargeter>
targeters

Constructor Summary

AccessConstructor and Description
protected
InstructionHandle(final Instruction i)

Method Summary

Modifier and TypeMethod and Description
public void
accept(final Visitor
Visitor object
v)

Convenience method, simply calls accept() on the contained instruction.

public void
addAttribute(final Object
the key object to store/retrieve the attribute
key, final Object
the attribute to associate with this handle
attr)

Add an attribute to an instruction handle.

protected void
addHandle()

Deprecated Does nothing as of 6.3.1.
Does nothing.
public void
addTargeter(final InstructionTargeter t)

Denote this handle is being referenced by t.

pack-priv void
dispose()

Delete contents, i.e., remove user access.

public Object
getAttribute(final Object
the key object to store/retrieve the attribute
key)

Gets attribute of an instruction handle.

public Collection<Object>

Returns:

all attributes associated with this handle
getAttributes()

public final Instruction
getInstruction()

pack-priv static InstructionHandle
getInstructionHandle(final Instruction i)

Factory method.

public final InstructionHandle
getNext()

public int

Returns:

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

public final InstructionHandle
getPrev()

public InstructionTargeter[]

Returns:

null, if there are no targeters
getTargeters()

public boolean
hasTargeters()

public void
removeAllTargeters()

Remove all targeters, if any.

public void
removeAttribute(final Object
the key object to retrieve the attribute
key)

Delete an attribute of an instruction handle.

public void
removeTargeter(final InstructionTargeter t)

Denote this handle isn't referenced anymore by t.

public void
setInstruction(final Instruction i)

Replace current instruction contained in this handle.

pack-priv final InstructionHandle
setNext(final InstructionHandle
the next to set
next)

pack-priv void
setPosition(final int pos)

Sets the position, i.e., the byte code offset of the contained instruction.

pack-priv final InstructionHandle
setPrev(final InstructionHandle
the prev to set
prev)

public Instruction
swapInstruction(final Instruction i)

Temporarily swap the current instruction, without disturbing anything.

public String

Returns:

a string representation of the contained instruction.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public String

Returns:

a (verbose) string representation of the contained instruction.
toString(final boolean verbose)

protected int

Returns:

additional offset caused by possible change of this instruction's length
updatePosition(final int
additional offset caused by preceding (variable length) instructions
offset, final int
the maximum offset that may be caused by these instructions
maxOffset)

Called by InstructionList.setPositions when setting the position for every instruction.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

attributesback to summary
private Map<Object, Object> attributes
EMPTY_ARRAYback to summary
public static final InstructionHandle[] EMPTY_ARRAY

Empty array.

Since
6.6.0
EMPTY_INSTRUCTION_TARGETER_ARRAYback to summary
pack-priv static final InstructionTargeter[] EMPTY_INSTRUCTION_TARGETER_ARRAY

Empty array.

i_positionback to summary
protected int i_position

Deprecated

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

Annotations
@Deprecated
instructionback to summary
private Instruction instruction
nextback to summary
private InstructionHandle next
prevback to summary
private InstructionHandle prev
targetersback to summary
private Set<InstructionTargeter> targeters

Constructor Detail

InstructionHandleback to summary
protected InstructionHandle(final Instruction i)

Method Detail

acceptback to summary
public void accept(final Visitor v)

Convenience method, simply calls accept() on the contained instruction.

Parameters
v:Visitor

Visitor object

addAttributeback to summary
public void addAttribute(final Object key, final Object attr)

Add an attribute to an instruction handle.

Parameters
key:Object

the key object to store/retrieve the attribute

attr:Object

the attribute to associate with this handle

addHandleback to summary
protected void addHandle()

Deprecated

Does nothing as of 6.3.1.

Does nothing.

Annotations
@Deprecated
addTargeterback to summary
public void addTargeter(final InstructionTargeter t)

Denote this handle is being referenced by t.

disposeback to summary
pack-priv void dispose()

Delete contents, i.e., remove user access.

getAttributeback to summary
public Object getAttribute(final Object key)

Gets attribute of an instruction handle.

Parameters
key:Object

the key object to store/retrieve the attribute

getAttributesback to summary
public Collection<Object> getAttributes()
Returns:Collection<Object>

all attributes associated with this handle

getInstructionback to summary
public final Instruction getInstruction()
getInstructionHandleback to summary
pack-priv static InstructionHandle getInstructionHandle(final Instruction i)

Factory method.

getNextback to summary
public final InstructionHandle getNext()
getPositionback to summary
public int getPosition()
Returns:int

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

getPrevback to summary
public final InstructionHandle getPrev()
getTargetersback to summary
public InstructionTargeter[] getTargeters()
Returns:InstructionTargeter[]

null, if there are no targeters

hasTargetersback to summary
public boolean hasTargeters()
removeAllTargetersback to summary
public void removeAllTargeters()

Remove all targeters, if any.

removeAttributeback to summary
public void removeAttribute(final Object key)

Delete an attribute of an instruction handle.

Parameters
key:Object

the key object to retrieve the attribute

removeTargeterback to summary
public void removeTargeter(final InstructionTargeter t)

Denote this handle isn't referenced anymore by t.

setInstructionback to summary
public void setInstruction(final Instruction i)

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

setNextback to summary
pack-priv final InstructionHandle setNext(final InstructionHandle next)
Parameters
next:InstructionHandle

the next to set

Since
6.0
setPositionback to summary
pack-priv void setPosition(final int pos)

Sets the position, i.e., the byte code offset of the contained instruction.

setPrevback to summary
pack-priv final InstructionHandle setPrev(final InstructionHandle prev)
Parameters
prev:InstructionHandle

the prev to set

Since
6.0
swapInstructionback to summary
public Instruction swapInstruction(final 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.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the contained instruction.

Annotations
@Override
toStringback to summary
public String toString(final boolean verbose)
Returns:String

a (verbose) string representation of the contained instruction.

updatePositionback to summary
protected int updatePosition(final int offset, final 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:int

additional offset caused by preceding (variable length) instructions

maxOffset:int

the maximum offset that may be caused by these instructions

Returns:int

additional offset caused by possible change of this instruction's length