Summary

Add a new factory method in java.lang.classfile.instruction.IncrementInstruction that allows specifying the opcode for an increment instruction to be iinc or wide iinc.

Problem

There is no way to construct a wide iinc instruction with narrow operands that fits in an iinc instruction in the Class-File API, aside from crafting bytecode manually and parsing such bytecode.

Even though such an instruction is niche, it is valid in the class file format and should be supported by the API.

Solution

Add a factory method that takes an overload of Opcode so users can specify the wide iinc opcode.

Specification

diff --git a/src/java.base/share/classes/java/lang/classfile/instruction/IncrementInstruction.java b/src/java.base/share/classes/java/lang/classfile/instruction/IncrementInstruction.java
index 352f83f529c..4054a06c3e2 100644
--- a/src/java.base/share/classes/java/lang/classfile/instruction/IncrementInstruction.java
+++ b/src/java.base/share/classes/java/lang/classfile/instruction/IncrementInstruction.java
@@ -82,6 +84,37 @@ public sealed interface IncrementInstruction extends Instruction
      * @throws IllegalArgumentException if {@code slot} or {@code constant} is out of range
      */
     static IncrementInstruction of(int slot, int constant) {
+    }
+
+    /**
+     * {@return an increment instruction}
+     * <p>
+     * {@code slot} must be {@link java.lang.classfile##u1 u1} and
+     * {@code constant} must be within {@code [-128, 127]} for
+     * {@link Opcode#IINC iinc}, or {@code slot} must be
+     * {@link java.lang.classfile##u2 u2} and {@code constant} must be
+     * within {@code [-32768, 32767]} for {@link Opcode#IINC_W wide iinc}.
+     *
+     * @apiNote
+     * The explicit {@code op} argument allows creating {@code wide} or
+     * regular increment instructions when {@code slot} and
+     * {@code constant} can be encoded with more optimized
+     * increment instructions.
+     *
+     * @param op the opcode for the specific type of increment instruction,
+     *           which must be of kind {@link Opcode.Kind#INCREMENT}
+     * @param slot the local variable slot to increment
+     * @param constant the increment constant
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#INCREMENT} or {@code slot} or
+     *         {@code constant} is out of range
+     * @since 27
+     */
+    static IncrementInstruction of(Opcode op, int slot, int constant) {
     }
 }