RFR: JDK-8240697: convert builders to high-level Content blocks

Pavel Rappo pavel.rappo at oracle.com
Tue Mar 10 21:16:54 UTC 2020


I agree with what you said, Jon. We should apply that pattern on a case-by-case
basis, where practical.

On a related note, I would be interested in having a look at some examples of
"conditional" and "iterative" content. Not sure if we'll be able to do anything
about it, but at the very least we'll see the boundaries of applicability of
that pattern.

> On 10 Mar 2020, at 20:49, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Responding to the comment about the conventions for building HTML trees ...
> 
> My experience (including in other projects that generate HTML) is that the "After:" style you propose works well as long as it is not too deeply nested.
> 
> It does not work so well when there is conditional content or iterative content ... and as much as I have come to appreciate streams, I believe they can be over-(ab)used in trying to force everything into a more functional paradigm.
> 
> When the code pattern does not work well, I find I prefer to make trees "bottom up", building the leaf components, before assembling them in a single step into a larger component.   This is in comparison to creating an empty enclosing component and then building and adding the individual child components.
> 
> And, all of these are better that some of the weirder patterns that exist in the code today.
> 
> -- Jon
> 
> On 03/09/2020 04:38 AM, Pavel Rappo wrote:
>> 2. Is it just me, or it is indeed hard to comprehend the structure of the HTML
>> being composed in some of the places? Maybe we could think of slightly bending
>> the code formatting rules for the sake of readability where practical?
>> 
>> Before:
>> 
>>     HtmlTree flexHeader = HtmlTree.HEADER()
>>             .setStyle(HtmlStyle.flexHeader)
>>             .add(header);
>> 
>>     HtmlTree flexContent = HtmlTree.DIV(HtmlStyle.flexContent)
>>             .add(HtmlTree.MAIN().add(mainContents))
>>             .add(footer);
>> 
>>     return HtmlTree.DIV(HtmlStyle.flexBox)
>>             .add(flexHeader)
>>             .add(flexContent);
>> 
>> After:
>> 
>>     return DIV(HtmlStyle.flexBox,
>>                HEADER(HtmlStyle.flexHeader
>>                    header
>>                ),
>>                DIV(HtmlStyle.flexContent,
>>                    MAIN(mainContents),
>>                    footer
>>                )
>>            );
>> 
>> Before:
>> 
>>     Content li = HtmlTree.LI(HtmlStyle.blockList, table);
>>     Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
>>     contentTree.add(ul);
>> 
>> After:
>> 
>>     contentTree.add(
>>         UL(HtmlStyle.blockList,
>>             LI(HtmlStyle.blockList, table)
>>         )
>>     );
>> 
>> One added benefit of structuring HTML generation like that is that the resulting
>> code is less error-prone. When no intermediate reference is created, it is much
>> harder to pass a single "Content" into multiple places (which would be a bug).
> 



More information about the javadoc-dev mailing list