State of jigsaw: Description of module file format?

[Reinier Zwitserloot]

Would it be possible to consider adding such a feature?

Three ways to go that come to mind:

A) Create a new section type for 'source', 'javadoc' and for 'license'.
Define the content of license to just be the license text. 'source' and
'javadoc' are analogous to the resources section, with SubSectionFileHeader
describing the files using the same path restrictions as class files, i.e.
the javadoc of my/package/name/MyClass.class is found in the javadoc
section, in the SubSection with path my/package/name/MyClass.html. The
source is in the 'source' section, SubSection my/package/name/MyClass.java.
Existing tooling (incl. netbeans, intelliJ, and eclipse) manage to figure
this out once you provide them 3 separate archive files, one with javadoc,
one with source, and one with class files, using the same model, so
presumably this should be enough.

B) Create a new section type for 'extra data'. Extra data sections have no
subsections, and the data associated with it starts with a
newline-terminated key string, such as "source" or "license", followed by
some data. Presumably for licenses this data will be the raw license text,
and for source files it will be an archive file stream, presumably in zip
format. This method is a little easier on the module description file
format and is easier to expand on later, but it requires 2 very different
processors for handling class data vs. source/javadoc data for tools.

C) Hack the functionality into the 'resources' section, using some accepted
initial path (src/ and api/ for example).



While option A requires some additional work in the jigsaw spec, it does
appear to offer some unique advantages:

* Tooling can use the same code they already use to read class data to read
javadoc/src.

* Any module file format consumer (including the JVM) can stream past the
javadoc/src or even jump right past if the module source is random access
by skipping the entire section; all that needs to be read to do this is the
section header (section type + size).

* No risk of different pseudo-standards as every IDE attempts to define
their own magic prefix path in the resource section for source/javadoc.

* Trivial to write size optimizer that strips sections out that aren't
required to run the module. It's not that much harder to write such a tool
in any of the other scenarios, but if 'src/' and 'api/' files in the
resource section are merely strongly assumed to be irrelevant but never
officially defined as such, this tool would not be entirely safe to use
(there's always a chance the app itself does need these files and picked an
unfortunate path name to store these resources into).



Looking at the buid side of existing module-esque systems, such as ivy and
maven, indicates there's a need for such a feature (for example, to publish
to maven-central, source and javadoc has to be there, and all 3 (production
jar, javadoc zip, and source zip) are as a rule available for any project
there.

>From a more practical standpoint, being able to see the API documentation
when using a library, or jump into the source either to just review how a
third party library's code works or to allow the debugger to jump into a
method call is a rather useful aspect, and all the 3 major IDEs have ways
to associate javadoc/source with a library dependency in order to
accomplish these things. It would be nice if a single module file is all
you need to download and link into your IDE or debugger without the hassle
of having to also ship the source and javadoc separately.

 --Reinier Zwitserloot



On Tue, Jan 24, 2012 at 17:07, <mark.reinhold at oracle.com> wrote:

> 2012/1/23 23:38 -0800, reinier at zwitserloot.com:
> > I noticed this document:
> > http://cr.openjdk.java.net/~mr/jigsaw/notes/jigsaw-big-picture-01
> >
> > Does not cover the module file format.
>
> No, not yet.  The Jigsaw project page links to a (slightly out-of-date)
> description, here:
>
>  http://cr.openjdk.java.net/~mr/jigsaw/notes/module-file-format/
>
> There is at present no provision for source code, javadoc, or license
> text.
>
> - Mark
>