Modules Support in JDK Tools

The Modules Project was inactive and was subsequently dissolved Oct 2023. The approach described here was superseded by Project Jigsaw.

Note that tools and their command line options are not standardized by the JCP. This page lists what will be supported in OpenJDK.

Java Launcher

The java launcher will support the following new options:

Usage: java [-options] class [args...]
           (to execute a class)

   or  java [-options] -jar file [args...]
           (to execute a jar file)

   or  java [-options] -jam file [args...]
           (to execute a jam file)

   or  java [-options] -jam file -modulemain org.foo [args...]
           (to execute a jam file with a specific class in the module )

   or  java [-options] -module module-name[:version-constraint] [args...]
           (to execute a module from system repository)

   or  java [-options] -module module-name[:version-constraint] -modulemain org.foo [args...]
           (to execute a module from system repository with a specific class in the module)

   or  java [-options] -repository location \
                       -module module-name[:version-constraint] [args...]
           (to execute a module from a repository)

   or  java [-options] -repository location \
                       -module module-name[:version-constraint] -modulemain foo.org [args...]
           (to execute a module from a repository with a specific class in the module)

Using the -jam option:

With the -jam file option, all JAM files in the directory containing the named JAM file will be in the system repository, and hence available to the application. The -jam option also supports a pack200 and gzip compressed jam file, with the extension .jam.pack.gz.

// Execute main class of the module in a JAM file
java -jam /home/steve/org.foo.Xml-2.1.jam

// Execute main class of the module in a JAM file
java -classpath foo-path -jam /home/steve/org.foo.Xml-2.1.jam

// Execute main class of the module in a compressed JAM file
java -jam /home/steve/org.foo.Xml-2.1.jam.pack.gz

Using the -module option

// Execute main class of the highest version of org.foo.Xml module
java -module org.foo.Xml

// Execute main class of the highest version of org.foo.Xml module 
// that is greater than 2.1.
java -module org.foo.Xml:2.1+

// Optionally can specify class path for the VM.
java -classpath foo-path -module org.foo.Xml:2.1+

 
// Execute a specific class in a module   
java -classpath foo-path -module org.foo.Xml:2.1+ -modulemain FooClass

Using the -repository and -module options

The -repository requires a -module option to be specified.

// Execute Module with an application repository from /xyz  
java -repository /xyz -module org.foo.Xml:2.1+

// A module can be executed along with -classpath to load legacy resources
java -classpath foobar.jar -repository http://foo.com/samplerepo \
   -module org.foo.Xml:2.1+

// Execute main class of the highest version of org.foo.Xml module 
// with an application repository from /xyz  
java -repository /xyz -module org.foo.Xml

Notes

Jam Packaging Tool

The jam tool packages the files that make up a module into a JAM archive file. Its options are patterned after the options of the jar command. A prototype of the jam command is available now and its options are listed below. The final version will likely support a number of additional options.

Usage: jam c[v0]fs jam-file superpackage-name files ...

For example:

// Create archive "org.foo.mymodule-1.0.jam" and build MODULE-INF/MODULE.METADATA
// from the superpackage "org.foo.mymodule"
jam cfs org.foo.mymodule-1.0.jam org.foo.mymodule .

JRepo: Repository Management Tool

The JRepo repository tool allows for inspection and modification of repositories.

Usage: jrepo <command> <flags> <options>

Some flags are common to most commands:

Users do have to type the entire command, just enough characters to distinguish it from other commands. For example, jrepo li runs the list command.

JRepo commands and associated args

The remaining commands at this point only proposals; they need more thought/investigation:

Notes, Questions, Open Issues

Other Tools

Other tools, owned by folks not directly engaged in the JSR 277 effort, will need changes to work with modules. Dave Bristor is coordinating ownership of the changes.

In general, these tools need access to modules similar to the way they currently need access to a classpath. We propose that the arguments as used with the java launcher be used, as appropriate. Most likely, only -repository and -module will be required.

langtools: javac, javap, javah, and javadoc

Owner: Jon Gibbons

Status: Under investigation and discussion; effort TBD. The tools do not all currently share a common front end; that may change.

jdb

Owner: Jim Holmlund

Status: Work agreed to in prinicple; effort TBD.

rmic

Owner: Peter Jones

Status: The JDK currently ships with 2 distinct copies of rmic:
  1. one which is "handcrafted" and supports iiop
  2. one which is based on javadoc but does not support iiop
The goal is to incorporate iiop support into the second of the above. Since it is based on javadoc, changes for passing through arguments such as -module will then be transparent, with no extra work required in rmic.

jrunscript

Owner: TBD

Status: It's not certain that we need to update this tool; if so then need to find the code's owner.

javaws

Owner: Deployment team

Status: Need to find an individual to own this.

pack200, unpack200

Owner: John Rose and/or Kumar Srinivasan

Status: Dave is in discussion with John re the nature of changes required.