API change proposal for Builders and Models

[Brian Goetz]

I would want to review the code further, but what is common to both of 
these is that they were introduced early in the refactoring process, and 
may have been rendered obsolete by later refactorings, so both of these 
seem credible to me.

BufferedXxxBuilder exists for composition of transforms; I think these 
builders might well be exposed to the transformed involved?

On 1/8/2024 12:52 PM, - wrote:
> 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/530ea177/attachment.htm>