Classfile API CodeBuilder::transforming clarification

[Adam Sotona]

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



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20230307/ed62de14/attachment-0001.htm>