Class dec.trek.Instruction

The Instruction object allows you to manipulate the instructions of a statement.

The Instruction class does not have a public constructor. To reach a statement’s instructions, you must use firstInstruction() or lastInstruction() in the Statement class, or override at(Instruction) in the Trek class.

The wide instruction is transparently supported. For example,  instruction.getOpcode() for a wide instruction returns the underlying opcode (e.g. astore or iinc). However you can determine whether an instruction is its normal or wide form by checking the value returned by instruction.getSize().

Method Summary

  • delete – deletes the statement from the method
  • getArrayLoad – returns the Instruction that loaded the array used by this instruction
  • getConstant – returns an Object containing the constant used by this instruction
  • getLocal – returns the Local object of the local variable used by this instruction
  • getMember – returns the Field or Method object of the member used by this instruction
  • getOpcode – returns the opcode of this instruction
  • getPc – returns the location of this instruction within its method
  • getReferenceArg – returns the object actually referenced by this instruction
  • getSize – returns the number of bytes used by this instruction
  • getStatement – returns the Statement object of its statement
  • getTarget – returns the PC this instruction can branch to
  • getType – returns the type of this instruction
  • next – returns the Instruction object of the next instruction in its statement
  • prev – returns the Instruction object of the previous statement in its statement
  • toMemberClass – returns a string containing the name of the member’s class
  • toMemberName – returns a string containing the member’s name
  • toString – returns a string containing the source code of this instruction

Methods

public void delete(String changid)

Deletes this instruction from the in-memory representation of its classfile.

Parameters:

changid – the change ID to assign to this code change, or null to assign "".

public Instruction getArrayLoad()

If this instruction processes an array element, getArrayLoad returns the Instruction that loaded the array. Otherwise it returns null.

public Object getConstant()

Returns an object containing the value of the constant used by this instruction, or null if it does not use a constant. An instruction that uses a hardwired constant (like iload_3) will return a non-null result. An instruction that uses a soft-wired constant (like ldc) will also return a non-null result.

Returns an Object object if this instruction uses the null constant, an Integer object if it uses an Integer constant, a String object if it uses a String constant, and so on.

public Local getLocal()

Returns a Local object if this instruction uses a local variable, or null otherwise. For instructions that process an array element, a non-null result is returned if the array happens to be a local variable.

public Member getMember()

Returns null if this instruction does not use a member. Returns the member used by this instruction if its classfile can be accessed via getClassFile. Otherwise an exception is thrown.

A Method object is returned if this instruction calls a method. A Field object is returned if it uses a field. This includes instructions that process an array element, if the array happens to be a field.

public int getOpcode()

Returns the opcode of this instruction, as defined in The Java Virtual Machine Specification. Symbols for each opcode are also provided.

public int getPc()

Returns the byte offset of this instruction within its method. The offset of a method’s first instruction is 0.

public Object getReferenceArg()

Returns this instruction's reference argument, or null if this kind of instruction has no such argument. For example, a Taload instruction accesses an array from the operand stack, but it does not itself contain a field or local reference. Similarly bipush contains a constant rather than referencing a constant from the pool. So getReferenceArg for both these instructions would return null.

For instructions that load or store fields, a FieldRef is returned. For method invokation instructions, a MethodRef is returned. For instructions that reference a class or array type (like instanceof), a TypeRef is returned. For iinc and instructions that load or store local variables, a Local is returned. For instructions that load a constant from the pool, a ValueRef is returned. Note that the returned object can be used as an argument to an append.

public int getSize()

Returns the number of bytes in this instruction.

public Statement getStatement()

Returns the Statement object of this instruction’s statement.

public int getTarget()

Returns -2 if this instruction is the branch in a switch statement. Returns -1 if it is an instruction that cannot branch. Returns the method-relative byte offset it can branch to if it is an if, goto, or jsr instruction.

public int getType()

Returns this instruction’s type. For example, if this instruction is a getfield, Trek.IN_LOADFIELD is returned.

public Instruction next()

Returns the Instruction object of its statement’s next instruction, or null if its statement has no more instructions. 

public Instruction prev()

Returns the Instruction object of its statement’s previous instruction, or null if its statement has no more instructions.

public String toMemberClass()

Returns a string containing the fully qualified class name of the instruction’s member, or null if the instruction uses no member. It does not require or read the member’s classfile.

public String toMemberName()

Returns a string containing the name of the instruction’s member, or null if the instruction uses no member. It does not require or read the member’s classfile.

 public String toString()

Returns a string containing the "assembler code" of this instruction.