Review request: jar tool to transform a plain jar file to a modular jar

[Mandy Chung]

  The jigsaw team discussed the option name and the location of the 
module metadata in the jar file.   We decide to follow the single letter 
convention for the option name and will use letter 'I' which is the 
closest one to specify a "module ID".

When module-info.class exists in the inputfiles, if the metadata is in 
META-INF/module-info.class, there will be two copies of 
module-info.class (module-info.class and META-INF/module-info.class) in 
the jar file.  It'd be error-prone for tools that manipulates the module 
metadata [1].  We decide to keep "module-info.class" as the path for the 
module metadata in a modular jar file as it's in the modulepath.

I'll send out a new webrev once I update the implementation.

Mandy
[1] 
http://openjdk.java.net/projects/jigsaw/doc/draft-java-module-system-requirements-12#manipulable-module-metadata

On 08/25/11 18:20, Mandy Chung wrote:
> I implemented the support in the jar tool to transform a plain JAR file
> to a modular JAR file [1]:
>    http://cr.openjdk.java.net/~mchung/jigsaw/webrevs/modularize-jar/
>
> Simple example:
> To modularize an existing jar file (two ways - see below):
>   $ jar uf astro.jar -module org.astro at 2.0
>   $ jar uf greetings.jar -C modules/com.greetings module-info.class
>   $ java -jar greetings.jar   # launch in legacy mode
>
> Installing a modular JAR file in the module library
>     $ jmod install greetings.jar astro.jar -L mlib
>
> Run in module mode
>     $ java -L mlib -m com.greetings
>
> Details:
> The jar tool provides a new option to transform a plain old JAR file
> into a modular JAR:
>    -module {module-name at version}
>       Generate META-INF/module-info.class entry in the JAR file [a]
>
> It is designed to handle simple cases that:
>    * requires the default Java platform module [b]
>    * exports all public types
>    * main entry point as specified in the manifest or in the 'e'
>      flag, if any
>    * infers the dependencies from 'Class-Path' attribute if it is
>      a modular JAR file, and the specific module name of
>      that version will be added in the module dependency [c].
>
> The jar tool will determine if the inputfiles include a
> "module-info.class" entry that indicates that it is a modular
> application.  If exists, it will create a modular JAR by copying
> the module-info.class file in the META-INF directory [d].
> The "-module" option is not required in this case.
>
> Initially I propose to use the GNU-style option (--module) but
> it should really be a separate project to have the existing
> command-line tools to support GNU-style options that deserves
> its own JEP [2].  I like the option be a long-name option rather
> than the traditional single letter option which I don't see such
> inconsistency is an issue or find a good letter for it :)
>
> Since the generated module-info.class is typically fairly simple,
> it doesn't seem really necessary to output the module-info.java
> and so didn't implement that.
>
> Implementation: I use the classfile library that Jon Gibbons wrote
> to generate the module-info.class.  Since Jon will be updating
> javac and classfile per the module-info spec [3], I modified
> ModuleExport_attribute and ModuleRequires_attribute classes in
> a simple way but the right change will come when they are updated
> per the proposed spec.
>
> Footnotes:
> [a] jarfile name tends to be unnamed or contains '-' character.
>     The module name will not be inferred from the jarfile name.
> [b] Private and internal APIs in the jdk are not exported.
>     If the JAR file depends on any of these APIs and running
>     in module mode, this will result in a runtime error.
> [c] If the path listed in the 'Class-Path' attribute is not a
>     modular JAR, it will simply issue a warning and continue.
>     Module dependencies may be incomplete in this case.
> [d] If an application has been modularized, module-info.java that
>     describes the module definition is placed in the root of the
>     source tree and compiled in the same destination directory as
>     its classes.
>
> BTW, I'm working on adding a new regression test for this new
> functionality. It looks like I have to write a better framework
> to cover different test cases and do the validation that may take
> some time.
>
> Thanks
> Mandy
>
> [1] 
> http://mail.openjdk.java.net/pipermail/jigsaw-dev/2011-April/001251.html
> [2] http://openjdk.java.net/jeps
> [3] 
> http://openjdk.java.net/projects/jigsaw/doc/topics/modules-classfile.html
>