RFR: 8344942: Template-Based Testing Framework [v25]

[Emanuel Peter]

On Thu, 15 May 2025 14:48:39 GMT, Manuel Hässig <mhaessig at openjdk.org> wrote:

>> Emanuel Peter has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   fix typo
>
> Thank you for the refactoring and your patience. I like the result and its simplicity a lot.
> 
> I found a few typos, but otherwise it looks excellent.

@mhaessig Thanks for your suggestions, I applied them all - or elaborated even further :)

> test/hotspot/jtreg/compiler/lib/template_framework/Renderer.java line 47:
> 
>> 45:     /**
>> 46:      * There can be at most one Renderer instance at any time. This is to avoid that users accidentally
>> 47:      * render templates to strings, rather than letting them all render together.
> 
> Suggestion:
> 
>      * There can be at most one Renderer instance at any time. This is to avoid users accidentally
>      * rendering templates to separate strings, rather than letting them all render together.
> 
> I do not understand the original sentence. My suggestion reflects what I understood.

Hmm, maybe I have to use more words to be more explicit. I replaced the two lines with this:

   45     /**
~  46      * There can be at most one Renderer instance at any time.
~  47      *
+  48      * When using nested templates, the user of the Template Framework may be tempted to first render
+  49      * the nested template to a {@link String}, and then use this {@link String} as a token in an outer
+  50      * {@link Template#body}. This would be a bad pattern: the outer and nested {@link Template} would
+  51      * be rendered separately, and could not interact. For example, the nested {@link Template} would
+  52      * not have access to the scopes of the outer {@link Template}. The inner {@link Template} could
+  53      * not access {@link Name}s and {@link Hook}s from the outer {@link Template}. The user might assume
+  54      * that the inner {@link Template} has access to the outer {@link Template}, but they would actually
+  55      * be separated. This could lead to unexpected behavior or even bugs.
+  56      *
+  57      * Instead, the user should create a {@link TemplateToken} from the inner {@link Template}, and
+  58      * use that {@link TemplateToken} in the {@link Template#body} of the outer {@link Template}.
+  59      * This way, the inner and outer {@link Template}s get rendered together, and the inner {@link Template}
+  60      * has access to the {@link Name}s and {@link Hook}s of the outer {@link Template}.
+  61      *
+  62      * The {@link Renderer} instance exists during the whole rendering process. Should the user ever
+  63      * attempt to render a nested {@link Template} to a {@link String}, we would detect that there is
+  64      * already a {@link Renderer} instance for the outer {@link Template}, and throw a {@link RendererException}.                                                                                                                          
   65      */

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

PR Comment: https://git.openjdk.org/jdk/pull/24217#issuecomment-2885825080
PR Review Comment: https://git.openjdk.org/jdk/pull/24217#discussion_r2092450471