org.apache.bcel.generic

## Class Instruction

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

- All Implemented Interfaces:
    Cloneable
  Direct Known Subclasses:
    ACONST_NULL, ArithmeticInstruction, ArrayInstruction, ARRAYLENGTH, ATHROW, BIPUSH, BranchInstruction, BREAKPOINT, ConversionInstruction, CPInstruction, DCMPG, DCMPL, DCONST, FCMPG, FCMPL, FCONST, ICONST, IMPDEP1, IMPDEP2, LCMP, LCONST, LocalVariableInstruction, MONITORENTER, MONITOREXIT, NEWARRAY, NOP, RET, ReturnInstruction, SIPUSH, StackInstruction

      public abstract class Instruction
      extends Object
      implements Cloneable

  Abstract super class for all Java byte codes.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected short` | `length` Deprecated. (since 6.0) will be made private; do not access directly, use getter/setter
    `protected short` | `opcode` Deprecated. (since 6.0) will be made private; do not access directly, use getter/setter

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Instruction(short opcode, short length)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `accept(Visitor v)` Call corresponding visitor method(s).
    `int` | `consumeStack(ConstantPoolGen cpg)` This method also gives right results for instructions whose effect on the stack depends on the constant pool entry they reference.
    `Instruction` | `copy()` Use with caution, since 'BranchInstruction's have a 'target' reference which is not copied correctly (only basic types are).
    `void` | `dump(DataOutputStream out)` Dumps instruction as byte code to stream out.
    `boolean` | `equals(Object that)` Tests for equality, delegated to comparator
    `static InstructionComparator` | `getComparator()` Deprecated. (6.0) use the built in comparator, or wrap this class in another object that implements these methods
    `int` | `getLength()`
    `String` | `getName()`
    `short` | `getOpcode()`
    `int` | `hashCode()` Gets the hashCode of this object.
    `protected void` | `initFromFile(ByteSequence bytes, boolean wide)` Reads needed data (e.g.
    `static boolean` | `isValidByte(int value)` Tests if the value can fit in a byte (signed)
    `static boolean` | `isValidShort(int value)` Tests if the value can fit in a short (signed)
    `int` | `produceStack(ConstantPoolGen cpg)` This method also gives right results for instructions whose effect on the stack depends on the constant pool entry they reference.
    `static Instruction` | `readInstruction(ByteSequence bytes)` Reads an instruction from (byte code) input stream and return the appropriate object.
    `static void` | `setComparator(InstructionComparator c)` Deprecated. (6.0) use the built in comparator, or wrap this class in another object that implements these methods
    `String` | `toString()`
    `String` | `toString(boolean verbose)` Long output format: <name of opcode> "["<opcode number>"]" "("<length of instruction>")"
    `String` | `toString(ConstantPool cp)`

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

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

- - ### Field Detail

    - #### length

          @Deprecated
          protected short length

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

    - #### opcode

          @Deprecated
          protected short opcode

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

  - ### Constructor Detail

    - #### Instruction

          public Instruction(short opcode,
                             short length)

  - ### Method Detail

    - #### getComparator

          @Deprecated
          public static InstructionComparator getComparator()

      Deprecated. (6.0) use the built in comparator, or wrap this class in another object that implements these methods
      Gets Comparator object used in the equals() method to determine equality of instructions.
      Returns:
        currently used comparator for equals()

    - #### isValidByte

          public static boolean isValidByte(int value)

      Tests if the value can fit in a byte (signed)
      Parameters:
        `value` - the value to check
      Returns:
        true if the value is in range
      Since:
        6.0

    - #### isValidShort

          public static boolean isValidShort(int value)

      Tests if the value can fit in a short (signed)
      Parameters:
        `value` - the value to check
      Returns:
        true if the value is in range
      Since:
        6.0

    - #### readInstruction

          public static Instruction readInstruction(ByteSequence bytes)
                                             throws IOException

      Reads an instruction from (byte code) input stream and return the appropriate object.

      If the Instruction is defined in `InstructionConst`, then the singleton instance is returned.

      Parameters:
        `bytes` - input stream bytes
      Returns:
        instruction object being read
      Throws:
        `IOException` - Thrown when an I/O exception of some sort has occurred.
      See Also:
        `InstructionConst.getInstruction(int)`

    - #### setComparator

          @Deprecated
          public static void setComparator(InstructionComparator c)

      Deprecated. (6.0) use the built in comparator, or wrap this class in another object that implements these methods
      Sets comparator to be used for equals().

    - #### accept

          public abstract void accept(Visitor v)

      Call corresponding visitor method(s). The order is: Call visitor methods of implemented interfaces first, then call methods according to the class hierarchy in descending order, i.e., the most specific visitXXX() call comes last.
      Parameters:
        `v` - Visitor object

    - #### consumeStack

          public int consumeStack(ConstantPoolGen cpg)

      This method also gives right results for instructions whose effect on the stack depends on the constant pool entry they reference.
      Returns:
        Number of words consumed from stack by this instruction, or Constants.UNPREDICTABLE, if this can not be computed statically

    - #### copy

          public Instruction copy()

      Use with caution, since 'BranchInstruction's have a 'target' reference which is not copied correctly (only basic types are). This also applies for 'Select' instructions with their multiple branch targets.
      Returns:
        (shallow) copy of an instruction
      See Also:
        `BranchInstruction`

    - #### dump

          public void dump(DataOutputStream out)
                    throws IOException

      Dumps instruction as byte code to stream out.
      Parameters:
        `out` - Output stream
      Throws:
        `IOException` - Thrown when an I/O exception of some sort has occurred.

    - #### equals

          public boolean equals(Object that)

      Tests for equality, delegated to comparator
      Overrides:
        `equals` in class `Object`
      Returns:
        true if that is an Instruction and has the same opcode

    - #### getLength

          public int getLength()

      Returns:
        length (in bytes) of instruction

    - #### getName

          public String getName()

      Returns:
        name of instruction, i.e., opcode name

    - #### getOpcode

          public short getOpcode()

      Returns:
        this instructions opcode

    - #### hashCode

          public int hashCode()

      Gets the hashCode of this object.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        the hashCode
      Since:
        6.0

    - #### initFromFile

          protected void initFromFile(ByteSequence bytes,
                                      boolean wide)
                               throws IOException

      Reads needed data (e.g. index) from file.
      Parameters:
        `bytes` - byte sequence to read from
        `wide` - "wide" instruction flag
      Throws:
        `IOException` - may be thrown if the implementation needs to read data from the file

    - #### produceStack

          public int produceStack(ConstantPoolGen cpg)

      This method also gives right results for instructions whose effect on the stack depends on the constant pool entry they reference.
      Returns:
        Number of words produced onto stack by this instruction, or Constants.UNPREDICTABLE, if this can not be computed statically

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`
      Returns:
        mnemonic for instruction in verbose format

    - #### toString

          public String toString(boolean verbose)

      Long output format: <name of opcode> "["<opcode number>"]" "("<length of instruction>")"
      Parameters:
        `verbose` - long/short format switch
      Returns:
        mnemonic for instruction

    - #### toString

          public String toString(ConstantPool cp)

      Returns:
        mnemonic for instruction with sumbolic references resolved

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