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.