<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
font-size:10.0pt;
font-family:"Calibri",sans-serif;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0cm;
margin-right:0cm;
margin-bottom:0cm;
margin-left:36.0pt;
font-size:10.0pt;
font-family:"Calibri",sans-serif;}
span.EmailStyle21
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:1108739289;
mso-list-type:hybrid;
mso-list-template-ids:326021772 1639768598 134807577 134807579 134807567 134807577 134807579 134807567 134807577 134807579;}
@list l0:level1
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level2
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level3
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level4
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level5
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level6
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
@list l0:level7
{mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level8
{mso-level-number-format:alpha-lower;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-18.0pt;}
@list l0:level9
{mso-level-number-format:roman-lower;
mso-level-tab-stop:none;
mso-level-number-position:right;
text-indent:-9.0pt;}
ol
{margin-bottom:0cm;}
ul
{margin-bottom:0cm;}
--></style>
</head>
<body lang="en-CZ" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">We are building structured documents with focus on visual aspect, which makes them human readable. Such documents are very complex trees with zillions of combinations
of various branch joints. <o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">These six classes (records) represent careful selection of such joints, so their combination (hopefully) covers all our needs for visually appearing class printing in
three major structured text formats.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Asymmetry of the joins exactly delimits permitted combinations. I didn’t validate it by test yet, however I expect any possible combination of Value, ValueList, Mapping,
BlockMapping, BlockList and Comment will always render into valid (and nicely styled) document in all three formats.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">I’ve been evaluating another two approaches:<o:p></o:p></span></p>
<ol style="margin-top:0cm" start="1" type="1">
<li class="MsoListParagraph" style="margin-left:0cm;mso-list:l0 level1 lfo1"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Separate data from formatting , so data can be hold in Map-of-Maps, while each mapping will be attributed by
a single Enum describing the formatting. However I found no simple way how to attribute LinkedHashMap (without implementing custom keys, values, entries or the whole Map). And also generic Map<String, Object> is not very specific API, the whole code restrictions
would have to move to Javadoc. Also implementation of each Printer will become a nightmare.
<o:p></o:p></span></li><li class="MsoListParagraph" style="margin-left:0cm;mso-list:l0 level1 lfo1"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Produce generic data as Map-of-Maps without any formatting attributes and match it by each printer with specific
“style” descriptor (matching by keys). However beside the same problems as in #1 it also ignores the fact the data must be produce with formatting in mind, or the printers code will be one big hell and there will be no way how to cover the combinations by
tests.<o:p></o:p></span></li></ol>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">I’m not sure how using generics can reduce actual number of 6 classes (records).<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Actual switch expression in each printer have exactly 6 cases to handle. When using generics we would need additional API and sub-switch to determine differences.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Theoretically we can make the tree a bit more square and add an Enum parameter to determine difference between Mapping, BlockMapping, ValueList and BlockList (for example
public record Mapping(String key, ShapeEnum shape, List<Printables>)), however it will more than double possible combinations of the joins. Each combination must be covered in each printer or to exclude in runtime and document in Javadoc and provided with
a test.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">To be more specific about the actual classes:<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Mapping accepts only fragments, because it must render as single line and for example in XML it renders as single element with attributes.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">It can hold single values or list of values, where the list is rendered into a single attribute value.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">It cannot hold another Mapping because we cannot embed XML element into an attribute (so that is we it implements printable).<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Rendering multiple elements on a single line is still valid XML document, however far from human readability.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">Mapping can represent a Fragment in JSON and in YAML, however XML throws an axe into that possibility.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">BlockMapping is the most powerful (multi-line indenting) joint, able to nest and render correctly another BlockMapping as well as any other Printable or Fragment.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">ValueList is restricted to leaf values (Strings, quoted String, numbers), because it is simple in all three formats. Construction of generic List of Fragments will require
printers to render tons of other joint combinations, which we simply do not need.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US">BlockList makes sense only in combination with BlockMappings. We would like to avoid BlockList of BlockLists as multi-level unnamed lists do not make much sense. Also
rendering lists with any other joints is useless. If you have list of classes, list of methods, or list of fields – it does not make sense to put any other Fragment, BlockList or Comment in between them. Theoretically we can replace BlockList with ListOfBlockMaps(String
key, String mapsKey, List<List<Printable>> printables), however that does not make anything easier nor smaller.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US" style="font-size:11.0pt;mso-fareast-language:EN-US"> <o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal" style="mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:12.0pt;margin-left:36.0pt">
<b><span style="font-size:12.0pt;color:black">From: </span></b><span style="font-size:12.0pt;color:black">Brian Goetz <brian.goetz@oracle.com><br>
<b>Date: </b>Monday, 25 July 2022 19:59<br>
<b>To: </b>Adam Sotona <adam.sotona@oracle.com><br>
<b>Cc: </b>classfile-api-dev@openjdk.org <classfile-api-dev@openjdk.org><br>
<b>Subject: </b>Re: Classfile API proposal to integrate basic print functionality directly to ClassModel and MethodModel<o:p></o:p></span></p>
</div>
<p class="MsoNormal" style="mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:12.0pt;margin-left:36.0pt">
<span style="font-size:13.5pt;font-family:"Courier New"">If "block" means multi-line, and non-block means single-line, I'm confused as to why we have<br>
<br>
public record Mapping(String key, List<Fragment> fragments) implements Printable {}<br>
but<br>
public record BlockMapping(String key, List<Printable> printables) implements Printable {}<br>
<br>
where one has fragments and the other only has Printables. Similarly, we have<br>
<br>
public record ValueList(String key, List<ConstantDesc> values) implements Fragment {}<br>
public record BlockList(String key, List<BlockMapping> blockMappings) implements Printable {}<br>
</span><br>
where again the List element differs. Is there no way to make the block/non-block orthogonal to the payload type? That would allow us to replace the two BlockXxx(...) with different payloads, with a Block<T> wrapper as a formatting hint.
<br>
<br>
<span style="font-size:11.0pt"><o:p></o:p></span></p>
<p class="MsoNormal" style="margin-left:36.0pt"><span style="font-size:11.0pt"><o:p> </o:p></span></p>
</div>
</body>
</html>