Java Module-System Requirements — DRAFT 12
Mark Reinhold
2011/4/19 21:20 -0700 [12]

Comments and discussion: jigsaw dash dev at openjdk dot java dot net

Module dependences · Resolution in all phases · Fidelity across all phases · Encapsulation · Versioning · Optional modules · Refactoring · Substitution · Module constraints on targets · Target constraints on modules · Native code · Services · Resources · Read-only operation · Platform modularization · Package subsets · Shared class loaders
Tool chain · Module declarations alongside source code · Exploded modules · Diagnostic messages · Diagnostic tooling · Debug libraries
Reification · Simultaneous multiple versions
4Migration and interoperation
Modular JAR files · JAR files depending upon modules · Modularize JAR files · Maven support · OSGi support · Extensible module declarations · Authoritative module declarations · Manipulable module metadata
Java-native module-file format · Signed module files · Java modules as native packages
Web publication · Exploratory installation
No performance regressions · Startup-time improvements · Enable future performance improvements
8Open requirements
“Friend” constraints · JSR 294 · Multi-platform installations · Predictability · Service declarations · Package-level dependences · Java-like syntax · Source-form metadata in modular JAR files · Compiled module declarations · Non-Java source-file names · Java source-file names
Fine-grained Java SE modularization
BChange history
CCommentary on module-metadata formats

The terms “must,” “must not,” “required,” “shall,” “shall not,” “should,” “should not,” “recommended,” “may,” and “optional” in this document are to be interpreted as described in RFC 2119.


Developers are the most important consumers of the module system. Those familiar with Maven, with OSGi bundles, with .NET assemblies, or with UNIX shared libraries should be immediately comfortable and productive with Java modules. The compile-link-debug cycle should be fast and they should be able to diagnose problems quickly. Features that don’t encourage best practices should be omitted.


Containers such as IDEs, Java EE containers, and applet containers are the second-most important constituency for the module system. They have specific requirements for dynamism and multiple-version support. For Java EE the primary use case should be an assumed future modular WAR standard in which a WAR file contains one or more Java modules.

Migration and interoperation 

In order to be adopted the module system must “play well” with existing file formats, tool chains, build systems, and module systems.

A primary use case for OSGi support is Eclipse. The adoption of Java modules will be hindered if they cannot easily be used in the context of Eclipse. An Eclipse plug-in for JPA, e.g., must be able to declare dependences upon standard JPA API modules as well as upon specific implementations.


In order to make Java more widely useful, i.e., beyond the usual Java EE and applet/JNLP scenarios, we should make it easy to package modules that contain both Java and native code. (This is also required for the modularization of the JDK itself.) We should also make it possible to package modules in the standard native-package formats of popular operating systems so that Java libraries and applications can be managed in the way most familiar to developers and end users.


Maven provides a way to publish Java code for web discovery and download at build time but it doesn’t work for deployers or end users when they need to install libraries and applications for use at run time. To make Java more widely useful it needs to catch up with Perl (which has CPAN), Python (PyPI), Ruby (Gems), and Scala (Bazaars).

Open requirements 

These requirements are not yet settled, pending further investigation. Some of these open requirements conflict with each other, as noted.

The following two requirements conflict. Please see Appendix C for commentary.

The following two requirements also conflict.


This document includes contributions from Alex Buckley, Jonathan Gibbons, Karen Kinnear, and Adam Messinger. It has been improved with the help of comments and suggestions from Roberto Chinnici, Jerome Dochez, Bill Shannon, David Bosschaert, BJ Hargrave, Doug Lea, and Jeff McAffer.

Change history 

Version 12

Version 11, 2011/4/19

Version 10, 2011/4/5

Version 9, 2011/3/29

Version 8, 2011/2/16

Commentary on module-metadata formats 

Among those who have reviewed this document there are divergent opinions as to whether module declarations must, or must not, be compiled by a Java compiler into a standard binary form. The arguments of each side are captured here for the record.

If module declarations are not compiled then they must remain in source form across all phases, i.e., the module metadata in a packaged module would be a textual copy of the original module declaration source code.

Arguments for requiring that module declarations not be compiled:

Arguments for requiring that module declarations be compiled: