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
• jam packaging tool
• JRepo: repository management tool
• Other tools

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

• The -jar, -jam and -module options are mutually exclusive.
• The version constraint syntax is defined in the JSR 277 specification.

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:

• -v: verbose - yields more output
• -r repositoryLocation: repository - location is filesystem path or URL to repository to be used

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

• list [-v] [-p] [-r repositoryLocation] [moduleNamePrefix]

  Lists the names and versions of modules in a repository. With -v, also gives platform, architecture, pathname, and last modified time (if available). With -p, includes parent repositories. With -r, uses the given repository, otherwise uses the repository determined by the repository configuration. Listed modules are displayed in the same order that Repository.find() would find them (i.e. bootstrap-repository-first). With a moduleNamePrefix, lists only those modules whose names match the prefix.

• install [-v] [-q] [-f] -r repositoryLocation JAMFile

  Installs the named JAMFile into the named repository, and checks that the module's dependencies are satisfied. -f forces installation even if another module with same characteristics (name, version, platform, architecture) is already installed. With -v, if the module uses a custom import policy, warns that the module's checks might not be sufficient to prevent runtime errors. With -q, does not do any checking. Note: Neither forcing installation via -f nor any checking are implemented yet; use of -q or -f yields a usage error.

• uninstall [-v] [-f | -i] -r repositoryLocation moduleName [ [moduleVersion] [modulePlatform-moduleArch] ]

  Uninstalls the identified module from the named repository. Fails if information given identifies more than one module, unless one of -f or -i is given. With -f, all modules identified are uninstalled. With -i, JRepo shows the user the matching modules, and asks which should be uninstalled.

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

• dependencies [-v] [-r repositoryLocation] [moduleName [ [moduleVersion] [modulePlatform-moduleArch] ] ]

  Lists all the modules on which the identified modules depend. If no moduleName, etc. are given, check dependencies of all modules in the repository.

• contents [-v] [-i] [-r repositoryLocation] moduleName [moduleVersion] [modulePlatform-moduleArch]

  Lists the contents of the identified module (e.g. similar to "ls -lR" or "jar tf"). Fails if the information given identifies more than one module, unless -i is given. With -i, JRepo shows the user the matching modules, and asks which should have its contents listed.

• get [-v] [-r repositoryLocation] [-n fileName] moduleName [moduleVersion] [modulePlatform-moduleArch]

  Creates a JAM file from the identified module. If -n is not given, uses the name of the module's corresponding file. If -n is given and names a directory, saves the JAM in the current directory using the name of the module's corresponding file. Otherwise, saves the JAM as the given moduleName.

• check [-v] [-r repositoryLocation] [ moduleName [ [moduleVersion] [modulePlatform-moduleArch] ] ]

  Runs shallow (or deep?) validationon the specified modules. If no module is specified, checks all modules in the repository.

Notes, Questions, Open Issues

• The repositoryLocation does not identify the type of the repository: the initial tool will treat it as a file system path or URL and use a Local or URLRepository as appropriate. In the fullness of time, we probably need some way to allow users to specify the kind of repository, e.g. a "-class clazz" or "-type serviceType" argument.
• It is TBD how the get and contents commands can trigger a download of enough information to satisfy their requirements. Currently, only modules for which the corresponding ModuleArchiveInfo instance has a file name could be handled.

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.

© 2025 Oracle Corporation and/or its affiliates
Terms of Use · License: GPLv2 · Privacy · Trademarks