Updated conformance text for Java SE 9 (JSR 379)

[Tim Ellison]

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