Classfile API CodeBuilder::transforming clarification

[Paul Sandoz]

When reviewing I found transforming to be the trickiest area and also the most impactful, and the jewel in the overall design. Hence a modest suggestion about the naming of transform vs. transforming, the difference of which is too subtle and confusing IMO. I did state in summarizing the review that this area likely needs some more soak time after integration.

Paul.


> On Mar 7, 2023, at 6:42 AM, Brian Goetz <brian.goetz at oracle.com> wrote:
> 
> 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 the transform to apply to the code built by the handler
>>      * @param handler the handler that receives a {@linkplain CodeBuilder} to
>>      * build the code.
>>      * @return this builder
>>      */
>>     default CodeBuilder 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>
>>      * Within this block, the {@link #startLabel()} and {@link #endLabel()} correspond
>>      * to the start and end of the block, and the {@link BlockCodeBuilder#breakLabel()}
>>      * also corresponds to the end of the block.
>>      *
>>      * @param handler handler that receives a {@linkplain BlockCodeBuilder} to
>>      * generate the body of the lexical block.
>>      * @param transform the transform to apply to the lexical block generated by handler
>>      * @return this builder
>>      */
>>     default CodeBuilder transformedBlock(Consumer<BlockCodeBuilder> handler, CodeTransform transform)
>>  
>> Or alternatively:
>>     default CodeBuilder transformBlock(Consumer<BlockCodeBuilder> handler, CodeTransform transform)
>>  
>> or:
>>     default CodeBuilder transformingBlock(Consumer<BlockCodeBuilder> handler, CodeTransform transform)
>>  
>> or just simple:
>>     default CodeBuilder block(Consumer<BlockCodeBuilder> handler, CodeTransform transform)
>>  
>>  
>> Please let me know which version do you prefer or propose alternatives.
>>  
>> Thanks,
>> Adam