[fwd] Re: Updated conformance text for Java SE 9 (JSR 379)

[mark.reinhold at oracle.com]

// Forwarding from jpms-spec-experts (376), for the record

2017/7/24 6:33:34 -0700, tim_ellison at uk.ibm.com:
> Now that Java has introduced the concept of an explicit "link" stage for 
> subsetting
> the platform code, I think the conformance definition should differentiate 
> between
> an implementation of the specification that is providing a set of modules 
> as open
> APIs, and an implementation of the specification that is solely used to 
> power a
> "closed-world" application.
> 
> In the one case, a conformant platform may be a subset, and should provide 
> a coherent
> set of modules that implement a well-defined development/runtime platform. 
>  In the other
> case the implementation is being subset to provide a runtime fit for a 
> particular
> purpose.
> 
> With this in mind, we can introduce two new definitions:
> 
> A “Platform Implementation“ of this specification means a set of modules 
> created to be
> run with a variety of application programs, or linked with a specific 
> application to
> produce an “Application Specific Implementation”, i.e. this is a library 
> and associated
> runtime.
> 
> An “Application Specific Implementation” of this specification means a set 
> of modules
> that are linked to a specific application such that the modules are not 
> observable at
> runtime to code outside the application, i.e. this is a closed-world 
> application.
> 
> 
> The conformance description would then go on to refer to these as follows:
> 
> A Platform Implementation of this specification must include the 
> `java.base`
> module, _i.e._, must make that module observable.  A Platform 
> Implementation may,
> further, include one or more additional Java SE modules so long as the
> set of Java SE modules that the Implementation includes is _closed_, …
> 
> An Application Specific Implementation of this specification is not 
> subject to the
> same conformance requirements as a Platform Implementation of this 
> specification.
> 
> 
> Please see further specific comments in-lined below.
> 
> Regards,
> Tim
> 
> mark.reinhold at oracle.com wrote on 11/07/2017 18:10:38:
>> Attached below is revised and expanded text for the "Conformance"
>> subsection of the "Modular platform" section [1] of the Java SE 9
>> (JSR 379) specification.  This text straddles both the JPMS and
>> Java SE 9 JSRs.  To keep all of the conformance language in one
>> convenient place I propose to include it only in the Java SE 9
>> specification.
>> 
>> This version clarifies some details in the previous version [2] and,
>> further, specifies the manner in which the strong encapsulation of
>> modules may be relaxed.
>> 
>> Comments welcome.
>> 
>> - Mark
>> 
>> [1] http://cr.openjdk.java.net/~iris/se/9/java-se-9-pr-spec/#s7
>> [2] http://mail.openjdk.java.net/pipermail/java-se-9-spec-experts/
>> 2017-May/000020.html
>> 
>> ----
>> 
>> Every Implementation of this Specification must include the `java.base`
>> module, _i.e._, must make that module observable.  An Implementation 
> may,
>> further, include one or more additional Java SE modules so long as the
>> set of Java SE modules that the Implementation includes is _closed_,
>> i.e., contains every Java SE module required, via `requires transitive`
>> directives, by any member of the set.  For a specific example, an
>> Implementation that contains just the `java.base`, `java.sql`,
>> `java.logging`, and `java.xml` modules is closed because the only
>> `requires transitive` dependences are from `java.sql` to `java.logging`
>> and `java.xml`,
> 
> and `java.base` if you are being transitive.
> 
>> and the latter two modules are members of the set.
>> 
>> The Technology Compatibility Kit (TCK) for this Specification will be
>> able to test all of the Java SE modules included in an Implementation,
> 
> consider: strike out "be able to"
> 
>> and it will require that set to be closed.  An Implementation that 
> passes
>> the TCK is considered to fully implement this Specification even if it
>> does not include all of the Java SE modules.
> 
> consider: "...TCK is considered to implement this Specification correctly 
> even if..."
> Saying it fully implements the spec with missing modules doesn't make 
> sense.
>  
>> If an Implementation of this Specification includes a Java SE module 
> then
> 
> How could an implementation of this specification *not* include an SE 
> module?
> 
>> it must fully implement the corresponding part of this Specification. It
>> must, in particular, implement every API element of that module 
> including
>> the module’s name, its exported packages, and any `requires 
> transitive`
>> dependences.  It must not export any of that module’s other packages
>> without qualification.
>> 
>> This Specification defines the Licensor Name Space on a module-by-module
>> basis.  Provided that an Implementation that fully implements this
>> Specification includes the required Licensor Name Space for each 
> included
> 
> consider: replace "required" by "entire"?
> 
>> module then it is not considered to subset the Licensor Name Space.
> 
> <snip>
>> An Implementation of this Specification may provide a means to create
>> further Implementations.  If it does so then any new Implementation must
>> satisfy the constraints of the preceding paragraphs but need not include
>> all of the modules present in the original Implementation.
> </snip>
> 
> Why must it be an implementation of the specification that creates a 
> further
> implementation?  Maybe it is a builder tool, linker, stripper, etc.
> 
>> As an aid to migration, an Implementation may relax the strong
>> encapsulation of the modules that it includes as follows:
>> 
>>  - An Implementation may provide a means to invoke its run-time system
>>    with one or more packages of one or more of its modules open to code
>>    in all unnamed modules, i.e., to code on the class path.
> 
> I suggest this should not be limited to invocation time, i.e. consider
> replacing this sentence with:
>     - An Implementation may provide a means to open one or more packages
>       of one or more of its modules to code in all unnamed modules, i.e.,
>       to code on the class path.
> 
>>    The first
>>    access to an element of such a package by a program via a reflection
>>    API must cause a warning to be issued on the standard error stream.
>>    Later accesses may also cause warnings to be issued.
> 
> This should be an implementation choice, not a spec requirement.
> It is not going to be possible to define a meaningful "warning", 
> especially
> in headless environments or places where the error console is not reified.
> 
> While I see the value in warnings at development time, requiring a warning
> for every runtime invocation is unreasonable.
> 
> What will the JCK be checking to ensure this requirement is met?
> 
>>  - An Implementation may, by default, open one or more packages of one
>>    or more of its modules to code in all unnamed modules.  If it does 
> so
>>    then it must issue warnings as described in the previous paragraph.
> 
> Consider: dropping this warnings requirement.
> 
>>    If it does so then it must, further, provide a means to invoke its
>>    run-time system without opening any packages of any of its modules.
>> 
>>    (The Reference Implementation's run-time system behaves this way by
>>     default, and because this is the default it can also be invoked
>>     without opening any of its packages via the command-line option
>>     `--illegal-access=deny`.)
> 
> <snip>
>>  - An Implementation may provide a means to request that additional
>>    warnings or debugging information, such as stack traces, be issued
>>    when elements of its open packages are accessed via a reflection 
> API.
>> 
>>    (The Reference Implementation's run-time system can be invoked with
>>     the command-line options `--illegal-access=warn` or
>>     `--illegal-access=debug` in order to request warnings or both
>>     warnings and stack traces, respectively, on each unique reflective
>>     access to any open Implementation package.)
> </snip>
> 
> I suggest taking out the text between the <snip> markers.
> This information is best provided in user docs rather than the conformance
> definition, otherwise there will be a very long list of what /may/ be 
> done.
> 
>> Future revisions of this Specification are expected to mandate that all
>> of an Implementation's modules be strongly encapsulated by default and,
>> eventually, to disallow the above-described relaxation.
>> 
>> As a further aid to migration, an Implementation may provide a means to
>> invoke its run-time system in a way that establishes additional
> 
> Change to remove reference to invocation time, e.g. "...provide a means to
> establish additional..."
> 
>> relationships between specific modules, identified by name, regardless 
> of
>> the original declarations of those modules and regardless of whether
>> those modules are included in the Implementation or are part of the
>> application being run:
>> 
>>  - One module can be made to read another module.
>> 
>>    (The Reference Implementation provides this capability via the
>>     `--add-reads` command-line option.)
>> 
>>  - A package of one module can be opened to another module.
>> 
>>    (The Reference Implementation provides this capability via the
>>     `--add-opens` command-line option.)
>> 
>>  - A package of one module can be exported to another module.
>> 
>>    (The Reference Implementation provides this capability via the
>>     `--add-exports` command-line option.)
>> 
>>  - A package of one module can be opened or exported to every unnamed
>>    module.
>> 
>>    (The Reference Implementation provides this capability by allowing
>>     the special token `ALL-UNNAMED` to be used as a target of the
>>     `--add-opens` and `--add-exports` command-line options.)
>> 
>> None of these capabilities, for any modules, may be operative by 
> default.
>> A future revision of this Specification may disallow these capabilities.
>> 
> 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number 
> 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU