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.