# Package java.lang.classfile.instruction

package java.lang.classfile.instruction

## Provides interfaces describing code instructions for the `java.lang.classfile` library.

The `java.lang.classfile.instruction` package contains interfaces describing code instructions. Implementations of these interfaces are immutable.

Unless otherwise specified, passing `null` or an array or collection containing a `null` element as an argument to a constructor or method of any Class-File API class or interface will cause a `NullPointerException` to be thrown.

## Reading of instructions

Instructions and pseudo-instructions are usually accessed from a `CodeModel`, such as `CodeModel::forEach`, and categorized by pattern-matching.

When read from `class` files, instructions are lazily inflated; the contents of these instructions, besides the bare structure, are not evaluated to speed up parsing. Instructions to users interest, such as those filtered by the pattern matching, have their contents read on demand, to avoid unnecessary reading of unrelated instructions in a code array.

Due to the lazy nature of `class` file parsing, `IllegalArgumentException` indicating malformed `class` file data can be thrown at any method invocation. For example, an instruction object for a `TypeCheckInstruction` may be obtained from a `CodeModel`, but the subsequent invocation of `.type()` may fail with `IllegalArgumentException` because the instruction refers to a bad constant pool index.

## Writing of instructions

Writing of instructions happen on `CodeBuilder`. The most basic way to write instructions is to pass an instruction object to `CodeBuilder::with`, which supports all valid instructions. Yet, `CodeBuilder` provides a lot of convenience factory methods for easy creation of instructions, named by their mnemonic. These accessors are more concise, and often more efficient at run-time than passing instruction objects.

Due to restrictions in the `class` file format, some instructions may not be representable in a `CodeBuilder`. In some scenarios, such as for `BranchInstruction`, Class-File API options control if alternatives can be used in code generation instead. Otherwise, they can be configured to fail-fast to ensure the parity of `CodeBuilder` commands with the generated `code` array data.

See Java Virtual Machine Specification:
  6.5 Instructions
Since:
  24

- Related Packages
  Package
  Description
  java.lang.classfile
  Provides classfile parsing, generation, and transformation library.
  java.lang.classfile.attribute
  Provides interfaces describing `class` file attributes for the `java.lang.classfile` library.
  java.lang.classfile.constantpool
  Provides interfaces describing constant pool entries for the `java.lang.classfile` library.
- Interfaces
  Class
  Description
  ArrayLoadInstruction
  Models an array load instruction in the `code` array of a `Code` attribute.
  ArrayStoreInstruction
  Models an array store instruction in the `code` array of a `Code` attribute.
  BranchInstruction
  Models a branching instruction (conditional or unconditional) in the `code` array of a `Code` attribute.
  CharacterRange
  A pseudo-instruction which models a single entry in the `CharacterRangeTable` attribute.
  ConstantInstruction
  Models a constant-load instruction in the `code` array of a `Code` attribute, including "intrinsic", "argument", and "load" constant instructions.
  ConstantInstruction.ArgumentConstantInstruction
  Models an "argument constant" instruction, which encodes the constant value in the instruction directly.
  ConstantInstruction.IntrinsicConstantInstruction
  Models an "intrinsic constant" instruction, which encodes the constant value in its opcode.
  ConstantInstruction.LoadConstantInstruction
  Models a "load constant" instruction, which encodes the constant value in the constant pool.
  ConvertInstruction
  Models a primitive conversion instruction in the `code` array of a `Code` attribute, such as `i2l`.
  DiscontinuedInstruction
  Marker interface for instruction discontinued from the `code` array of a `Code` attribute.
  DiscontinuedInstruction.JsrInstruction
  Models jump subroutine instructions discontinued from the `code` array of a `Code` attribute since class file major version 51 (JVMS 4.9.1).
  DiscontinuedInstruction.RetInstruction
  Models return from subroutine instructions discontinued from the `code` array of a `Code` attribute since class file major version 51 (JVMS 4.9.1).
  ExceptionCatch
  A pseudo-instruction modeling an entry in the `exception_table` array of a `Code` attribute.
  FieldInstruction
  Models a field access instruction in the `code` array of a `Code` attribute.
  IncrementInstruction
  Models a local variable increment instruction in the `code` array of a `Code` attribute.
  InvokeDynamicInstruction
  Models a dynamically-computed call site invocation instruction in the `code` array of a `Code` attribute.
  InvokeInstruction
  Models a method invocation instruction in the `code` array of a `Code` attribute, other than `invokedynamic`.
  LabelTarget
  A pseudo-instruction which indicates that the specified label corresponds to the current position in the `Code` attribute.
  LineNumber
  A pseudo-instruction which indicates the code for a given line number starts after the current position in a `Code` attribute.
  LoadInstruction
  Models a local variable load instruction in the `code` array of a `Code` attribute.
  LocalVariable
  A pseudo-instruction which models a single entry in the `LocalVariableTable` attribute.
  LocalVariableType
  A pseudo-instruction which models a single entry in the `LocalVariableTypeTable` attribute.
  LookupSwitchInstruction
  Models a `lookupswitch` instruction in the `code` array of a `Code` attribute.
  MonitorInstruction
  Models a `monitorenter` or `monitorexit` instruction in the `code` array of a `Code` attribute.
  NewMultiArrayInstruction
  Models a `multianewarray` instruction in the `code` array of a `Code` attribute.
  NewObjectInstruction
  Models a `new` instruction in the `code` array of a `Code` attribute.
  NewPrimitiveArrayInstruction
  Models a `newarray` instruction in the `code` array of a `Code` attribute.
  NewReferenceArrayInstruction
  Models a `anewarray` instruction in the `code` array of a `Code` attribute.
  NopInstruction
  Models a `nop` instruction in the `code` array of a `Code` attribute.
  OperatorInstruction
  Models an arithmetic operator instruction in the `code` array of a `Code` attribute.
  ReturnInstruction
  Models a return-from-method instruction in the `code` array of a `Code` attribute.
  StackInstruction
  Models a stack manipulation instruction in the `code` array of a `Code` attribute.
  StoreInstruction
  Models a local variable store instruction in the `code` array of a `Code` attribute.
  SwitchCase
  Models a single case in a `lookupswitch` or `tableswitch` instruction.
  TableSwitchInstruction
  Models a `tableswitch` instruction in the `code` array of a `Code` attribute.
  ThrowInstruction
  Models an `athrow` instruction in the `code` array of a `Code` attribute.
  TypeCheckInstruction
  Models an `instanceof` or a `checkcast` instruction in the `code` array of a `Code` attribute.