API change proposal for Builders and Models

[-]

Hello Class-File API list,
I have 2 API change recommendations for CF Builders and Models:
1. Remove all original() methods in ClassBuilder, MethodBuilder,
FieldBuilder, and CodeBuilder.
2. Make all parent() methods return directly (than wrapping in an Optional)
for MethodModel, FieldModel, and CodeModel.

Rationale:
1. Removal of original() methods
All builders are only accessible as lambda parameters only in Class-File
API; and whether these builders are spinning new objects or transforming
existing models is already determined by entrypoint methods, such as
ClassBuilder::withMethod vs ClassBuilder::transformMethod. It's unlikely
for a user to share Consumer<XxxBuilder> for these distinct entrypoint
methods. If needed, users can simply capture the existing
class/method/field/code models they pass, instead of calling `original` and
unwrapping the risky Optional.

Currently, these methods have no usage within the JDK parts that migrated
to Class-File API, except delegation in chained/buffered implementations.
So the impact would be minimal.

2. Conversion of parent() methods to return directly instead of Optional
When we examine the XxxModel implementations, we can find they may be
non-bound in BufferedXxxBuilder.Model. However, these models, upon closer
inspection, are not visible to users at all; they are purely created to
serve as a stub ClassElement or MethodElement, to be passable to the
ClassFileBuilder::with methods. Thus, we should make parent() always return
directly instead of returning Optional.

Currently, there are many usages of parent() methods within the JDK; all of
them are immediately followed by a .get() or .orElseThrow() call, so this
change can be helpful API-wise. In addition, there are other UOE-stubbed
methods in these Models, notably BufferedMethodBuilder::code. Thus, the
implementation changes can be as simple as changing those methods to throw
UOE instead (for they shouldn't be visible to users first and foremost)


What do you think of these 2 proposals? Any feedback is welcome.

Chen Liang
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20240108/b5a131cd/attachment.htm>