Revisit j.l.classfile.CodeBuilder API surface

[Adam Sotona]

Hi,
j.l.classfile.CodeBuilder API consist of more than 230 methods.
Existing ClassFile API use cases proved the concept of one big CodeBuilder is comfortable. However there are some redundancies, glitches in the naming, some frequently used methods are hard to find and some methods have low practical use.

Majority of the methods may be divided into three main levels:
1. methods building low level bytecode instructions according to JVMS chapter 6.5 (aaload, aastore, aconst_null...)
2. methods reconstructing individual subtypes of j.l.classfile.Instruction from given arguments (loadInstruction, storeInstruction, incrementInstruction, branchInstruction...)
3. methods modeling high level code blocks (block, ifThen, ifThenElse, trying...)

Many methods from level 2 (with suffix `Instruction`) seem to be obsolete or misplaced. Some of them are duplicates of methods from level 1, some are obsolete and some are very useful, however a bit hidden. The API should be cleaned a bit while in preview.

I would like to open a discussion on the following proposed changes in the CodeBuilder methods:

  *   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 rename to newObject
  *   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_
Here is the related RFE: https://bugs.openjdk.org/browse/JDK-8323058
Draft of the CSR (no spec yet): https://bugs.openjdk.org/browse/JDK-8323067
And draft of the Pull Request: https://github.com/openjdk/jdk/pull/17282

Any comments are welcome.

Thank you,
Adam
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20240105/7154e9e2/attachment-0001.htm>