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