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
- 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>
-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.
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
andcontents
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:- one which is "handcrafted" and supports iiop
- one which is based on javadoc but does not support iiop
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.