JDK-8323067 : Revisit j.l.classfile.CodeBuilder API surface
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.lang.classfile
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 23
  • Submitted: 2024-01-05
  • Updated: 2024-05-01
  • Resolved: 2024-05-01
Related Reports
CSR :  
Relates :  
Relates :  
Description
Summary
-------

Remove redundancies and fix naming of `java.lang.classfile.CodeBuilder` API methods. 

Problem
-------

`CodeBuilder` contains more than 230 API methods.

Existing ClassFile API use cases proved that having one big CodeBuilder class works well in practice. However there are some redundant methods, glitches in the naming conventions, some frequently used methods are hard to find and some methods have low practical use.

Solution
--------

Suggested changes in `CodeBuilder` methods (all overrides):

 - `incrementInstruction` remove as duplicate of `iinc`
 - `lookupSwitchInstruction` remove as duplicate of `lookupswitch`
 - `tableSwitchInstruction` remove as duplicate of `tableswitch`
 - `throwInstruction` remove as duplicate of `athrow`
 - `invokeDynamicInstruction` remove as duplicate of `invokedynamic`
 - `stackInstruction` remove as obsolete with suggested replacements:  `with(StackInstruction.of(...))`
 - `monitorInstruction` remove as obsolete with suggested replacements: `monitorenter`, `monitorexit`, or `with(MonitorInstruction.of(...))`
 - `nopInstruction` remove as duplicate of `nop`
 - `typecheckInstruction` remove as obsolete with suggested replacements: `checkcast`, `instanceOf`, or `with(TypeCheckInstruction.of(...))`
 - `loadInstruction` rename to `loadLocal`
 - `storeInstruction` rename to `storeLocal`
 - `branchInstruction` rename to `branch`
 - `invokeInstruction` rename to `invoke`
 - `newObjectInstruction` remove as duplicate of `new_`
 - `newPrimitiveArrayInstruction` rename to `newPrimitiveArray`
 - `newReferenceArrayInstruction` rename to `newReferenceArray`
 - `newMultidimensionalArrayInstruction` rename to `newMultidimensionalArray`
 - `arrayLoadInstruction` rename to `arrayLoad`
 - `arrayStoreInstruction` rename to `arrayStore`
 - `convertInstruction` rename to `conversion`
 - `operatorInstruction` rename to `operator`
 - `constantInstruction` rename to `loadConstant`
 - `fieldInstruction` rename to `fieldAccess`
 - `instanceof_` rename to `instanceOf`
 - `returnInstruction` rename to `return_`

Specification
-------------

```
src/java.base/share/classes/java/lang/classfile/CodeBuilder.java:
+ arrayLoad(java.lang.classfile.TypeKind)
- arrayLoadInstruction(java.lang.classfile.TypeKind)
+ arrayStore(java.lang.classfile.TypeKind)
- arrayStoreInstruction(java.lang.classfile.TypeKind)
+ branch(java.lang.classfile.Opcode,java.lang.classfile.Label)
- branchInstruction(java.lang.classfile.Opcode,java.lang.classfile.Label)
- constantInstruction(java.lang.classfile.Opcode,java.lang.constant.ConstantDesc)
- constantInstruction(java.lang.constant.ConstantDesc)
+ conversion(java.lang.classfile.TypeKind,java.lang.classfile.TypeKind)
- convertInstruction(java.lang.classfile.TypeKind,java.lang.classfile.TypeKind)
+ fieldAccess(java.lang.classfile.Opcode,java.lang.classfile.constantpool.FieldRefEntry)
+ fieldAccess(java.lang.classfile.Opcode,java.lang.constant.ClassDesc,java.lang.String,java.lang.constant.ClassDesc)
- fieldInstruction(java.lang.classfile.Opcode,java.lang.classfile.constantpool.FieldRefEntry)
- fieldInstruction(java.lang.classfile.Opcode,java.lang.constant.ClassDesc,java.lang.String,java.lang.constant.ClassDesc)
- incrementInstruction(int,int)
+ instanceOf(java.lang.classfile.constantpool.ClassEntry)
+ instanceOf(java.lang.constant.ClassDesc)
- instanceof_(java.lang.classfile.constantpool.ClassEntry)
- instanceof_(java.lang.constant.ClassDesc)
+ invoke(java.lang.classfile.Opcode,java.lang.classfile.constantpool.MemberRefEntry)
+ invoke(java.lang.classfile.Opcode,java.lang.constant.ClassDesc,java.lang.String,java.lang.constant.MethodTypeDesc,boolean)
- invokeDynamicInstruction(java.lang.classfile.constantpool.InvokeDynamicEntry)
- invokeDynamicInstruction(java.lang.constant.DynamicCallSiteDesc)
- invokeInstruction(java.lang.classfile.Opcode,java.lang.classfile.constantpool.MemberRefEntry)
- invokeInstruction(java.lang.classfile.Opcode,java.lang.constant.ClassDesc,java.lang.String,java.lang.constant.MethodTypeDesc,boolean)
+ loadConstant(java.lang.classfile.Opcode,java.lang.constant.ConstantDesc)
+ loadConstant(java.lang.constant.ConstantDesc)
- loadInstruction(java.lang.classfile.TypeKind,int)
+ loadLocal(java.lang.classfile.TypeKind,int)
- lookupSwitchInstruction(java.lang.classfile.Label,java.util.List)
- monitorInstruction(java.lang.classfile.Opcode)
- newMultidimensionalArrayInstruction(int,java.lang.classfile.constantpool.ClassEntry)
- newMultidimensionalArrayInstruction(int,java.lang.constant.ClassDesc)
- newObjectInstruction(java.lang.classfile.constantpool.ClassEntry)
- newObjectInstruction(java.lang.constant.ClassDesc)
- newPrimitiveArrayInstruction(java.lang.classfile.TypeKind)
- newReferenceArrayInstruction(java.lang.classfile.constantpool.ClassEntry)
- newReferenceArrayInstruction(java.lang.constant.ClassDesc)
- nopInstruction()
- operatorInstruction(java.lang.classfile.Opcode)
- returnInstruction(java.lang.classfile.TypeKind)
+ return_(java.lang.classfile.TypeKind)
- stackInstruction(java.lang.classfile.Opcode)
- storeInstruction(java.lang.classfile.TypeKind,int)
+ storeLocal(java.lang.classfile.TypeKind,int)
- tableSwitchInstruction(int,int,java.lang.classfile.Label,java.util.List)
- throwInstruction()
- typeCheckInstruction(java.lang.classfile.Opcode,java.lang.classfile.constantpool.ClassEntry)
- typeCheckInstruction(java.lang.classfile.Opcode,java.lang.constant.ClassDesc)
```

Comments
Moving to Approved. As a consideration for a future enhancement, adding links from the CodeBuilder methods to the JMVS section for the corresponding instruction might be helpful to users to see what the special cases for the instruction are.
01-05-2024

Reviewed by and finalized. Thank you.
02-04-2024

Moving back to Provisional. [~asotona], please have more or more engineers review this CSR before re-Finalizing it.
29-02-2024

Moving to Provisional.
13-02-2024