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

[Emanuel Peter]

On Wed, 5 Nov 2025 09:02:18 GMT, Christian Hagedorn <chagedorn at openjdk.org> wrote:

>> Emanuel Peter has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   small adjustments after call with Roberto and Christian
>
> test/hotspot/jtreg/testlibrary_tests/template_framework/examples/TestTutorial.java line 736:
> 
>> 734:     //
>> 735:     // To get started, we show an example where all DataNames have the same type, and where
>> 736:     // all Names are mutable. For simplicity, our type represents the primitive int type.
> 
> Side note: Now that we also have the library available, could we also use that one instead of defining our own `MySimpleInt`? If so, you might want to show an example and hint here that you could also just define your own type as an expert user.

Hmm. You have a point. The situation has shifted a little.

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

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

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. 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?

> 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 ;)

> test/hotspot/jtreg/testlibrary_tests/template_framework/examples/TestTutorial.java line 784:
> 
>> 782:                     // If we are also interested in the type of the field, we can do:
>> 783:                     """,
>> 784:                     dataNames(MUTABLE).exactOf(mySimpleInt).sampleAndLetAs("b", "bType"),
> 
> Just a suggestion: We could be more explicit to mention that the second one is the type like `sampleToWithType()` or something like that.

Hmm. What about `sampleAndLetNameAs` and `SampleAndLetNameAndTypeAs`?

But that feels a bit too verbose. And I don't feel great about dropping the `let`.

People can always follow the method name to its definition, and find the javadocs there... :man_shrugging:

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494213676
PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494218306
PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2494228917