RFR: 8367531: Template Framework: use scopes and tokens instead of misbehaving immediate-return-queries [v11]

[Christian Hagedorn]

On Wed, 5 Nov 2025 12:15:15 GMT, Emanuel Peter <epeter at openjdk.org> wrote:

> Still, I think it is good if people understand how types work, so I'd leave it in as an example.

Yes, absolutely. I would not remove this example that shows how you can control everything in your own way.

> So for now, I'm just adding a note that we already have some types modeled in the library, for example with PrimitiveType.

That sounds good!

> But we have a bit of a fundamental issue here: if you expect TestTutorial.java to always give you the best practice with the most fresh things from the library, then we would have to constantly rework the tutorial. That would be a lot of work, especially if we continue adding more and more features.

Totally, that is the blessing and curse of having a thorough README.

> This concern is also a bit separate to the current RFE's intentions. So maybe we have to revisit the issue of how to present the library capabilities in the most efficient way, and to see if TestTutorial.java is the right place. Or maybe this tutorial just shows the core capabilities of the template framework, and we have some other tutorial that gives more insight into the library?

Could be an option to use `TestTutorial.java` for that or have some other tutorials like the IR Framework which presents different example files for different features. We could come back to this discussion later again. But either way, I think leaving the note below is perfectly fine for now to not give the impression that you need code everything from scratch if you just want to use some common cases.

>> test/hotspot/jtreg/testlibrary_tests/template_framework/examples/TestTutorial.java line 778:
>> 
>>> 776:                     // the hashtag replacement "a".
>>> 777:                     """,
>>> 778:                     dataNames(MUTABLE).exactOf(mySimpleInt).sampleAndLetAs("a"),
>> 
>> What do you think about just naming it `sampleTo("a")`? Or do you think the mention of `let` is crucial here?
>
> I think I slightly prefer `sampleAndLetAs` because of the `let`. But if you can get @robcasloz or @mhaessig to agree with you, I'm happy to change it ;)

Fair point. To me it just sounded a bit verbose but maybe Roberto and/or Manuel can break the tie :-) And if there is no clear consensus just stick with what you have now.

> But that feels a bit too verbose.

Indeed.

> People can always follow the method name to its definition, and find the javadocs there... 🤷‍♂️

That's true. You can leave it as it is now.

>> test/hotspot/jtreg/testlibrary_tests/template_framework/tests/TestTemplate.java line 469:
>> 
>>> 467:         var hook1 = new Hook("Hook1");
>>> 468: 
>>> 469:         var template0 = Template.make(() -> scope("t0 isAnchored: ", hook1.isAnchored(a -> scope(a)), "\n"));
>> 
>> You could directly use `Template::scope` instead of `a -> scope(a)`. Same below.
>
> But is that really more readable? I fear not really. And it is also longer... I'm a little torn with these. @robcasloz @mhaessig what are your votes?
> 
> Before:
> `"t2 isAnchored: ", hook1.isAnchored(a -> scope(a)), "\n",`
> After:
> `"t2 isAnchored: ", hook1.isAnchored(Template::scope), "\n",`

I just suggested it because the IDE marked it as improvement opportunity. Feel free to ignore.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494537592
PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494548702
PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494565818
PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494578751