RFR 8150681 Update JAR specification for multi-release jar files

[Paul Sandoz]

New update here:

http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/src/java.base/share/specs/jar/jar.md.sdiff.html <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/src/java.base/share/specs/jar/jar.md.sdiff.html>

I accepted most comments directly. I shuffled around the paragraphs in the modular jar section, partially in preparation for any changes and further explanations for automatic modules.

Paul.


> On 4 May 2017, at 08:41, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> On 03/05/2017 22:44, Paul Sandoz wrote:
> 
>> Hi,
>> 
>> Please review an update to the JAR “specification” (in the loose sense of the term):
>> 
>> - first, it has been moved from a closed repository into the idk repository (same shared location as the recently introduced serialisation specification) and converted to markdown:
>> 
>>   http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown/webrev/ <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown/webrev/>
>> 
>> (This also includes a new attribute Launcher-Agent-Class, a Jigsaw related change to better support Java agents.)
>> 
>> For comparison, the HTML version online is here:
>> 
>>   http://download.java.net/java/jdk9/docs/technotes/guides/jar/jar.html <http://download.java.net/java/jdk9/docs/technotes/guides/jar/jar.html>
>> 
>> - second i have added sections on multi-release JAR files:
>> 
>>   http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/ <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/>
>> 
>> this is based against the first patch so the changes can be easily viewed.
>> 
>> 
>> I expect some further editing of this specification to add further links to module related stuff and tidy up existing links to tools etc.
>> 
> I read through the changes.
> 
> Modular JAR files section:
> 
> "directly under the root"  - somewhat subjective but I think "in the top-level directory" as we had in the original text is clearer here.
> 
> "in accordance with it's module descriptor"  looks unusual and I think would be better to keep the original sentence.
> 
> L70 - I assume "explicitly modular or automatic" should be removed as this is JAR files on the class path.
> 
> Modular multi-release JAR files section:
> 
> As with the Modular JAR file section, I think "in the top-level directory" would be clearer.
> 
> L155-158 - "A non-exported public or protected class  ...". It might be clearer to say a public or protected class in a non-exported package.
> 
> L171 - I think there is a typo here and it means non-transitive requires.
> 
> Typo at L219: "This directory containers underneath"
> 
> Otherwise looks good to me.
> 
> -Alan