Classfile API CodeBuilder::transforming clarification

[Brian Goetz]

I'd like some time to think about this; this was one of the trickiest 
corners of the API to design.  Its quite possible there's an 
inconsistency or vestige, but also possible something subtle is going on.

Can we put this on the RFE list as well?

On 3/7/2023 5:09 AM, Adam Sotona wrote:
>
> Hi,
>
> During the Classfile API reviews there have been raised concerns about 
> `CodeBuilder::transforming` method, for details see:
>
> https://github.com/openjdk/jdk/pull/10982/files/074dd30401a68638a24c157595caeb96b3511614#r1123858513
>
> I would like to (re-)open this discussion here to find the best 
> suitable form of the following method:
>
> /**
>      * *Apply**a**transform**to**the**code**built**by**a**handler, 
> directing**results**to**this**builder.*
>      *
>      * *@param*transform thetransformtoapplytothecodebuiltbythehandler
>      * *@param*handler thehandlerthatreceivesa 
> {*@linkplain*CodeBuilder} to
>      * buildthecode.
>      * *@return*thisbuilder
> */
> defaultCodeBuilder *transforming*(CodeTransform transform, 
> Consumer<CodeBuilder> handler)
>
> My proposal is to align it more with `CodeBuilder::block` method and 
> emphasize more the bytecode block than the transformation itself.
>
> I propose to change the method name and arguments to:
>
> /**
>
>      * 
> *Add**a**transformed**lexical**block**to**the**method**being**built.*
>
>      * *<p>*
>
>      * Withinthisblock, the {*@link*#startLabel()} and 
> {*@link*#endLabel()} correspond
>
>      * tothestartandendoftheblock, andthe 
> {*@link*BlockCodeBuilder#breakLabel()}
>
>      * alsocorrespondstotheendoftheblock.
>
>      *
>
>      * *@param*handler handlerthatreceivesa 
> {*@linkplain*BlockCodeBuilder} to
>
>      * generatethebodyofthelexicalblock.
>
>      * *@param*transform 
> thetransformtoapplytothelexicalblockgeneratedbyhandler
>
>      * *@return*thisbuilder
>
> */
>
> defaultCodeBuilder *transformedBlock*(/Consumer/</BlockCodeBuilder/> 
> handler, /CodeTransform/ transform)
>
> Or alternatively:
>
> defaultCodeBuilder *transformBlock*(/Consumer/</BlockCodeBuilder/> 
> handler, /CodeTransform/ transform)
>
> or:
>
> defaultCodeBuilder 
> *transform**ing**Block*(/Consumer/</BlockCodeBuilder/> handler, 
> /CodeTransform/ transform)
>
> or just simple:
>
> defaultCodeBuilder *b**lock*(/Consumer/</BlockCodeBuilder/> handler, 
> /CodeTransform/ transform)
>
> Please let me know which version do you prefer or propose alternatives.
>
> Thanks,
>
> Adam
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20230307/6b05c60c/attachment-0001.htm>