JEP 201: Modular Source Code

AuthorMark Reinhold
OwnerAlan Bateman
Created2014/07/22 14:08
Updated2017/03/08 13:58
StatusCompleted / Delivered
Discussionjigsaw dash dev at openjdk dot java dot net
Reviewed byAlan Bateman, Alex Buckley, Mandy Chung, Paul Sandoz
Endorsed byBrian Goetz
BlocksJEP 200: The Modular JDK
Relates toJEP 220: Modular Run-Time Images


Reorganize the JDK source code into modules, enhance the build system to compile modules, and enforce module boundaries at build time.


This JEP will not change the structure of the JRE and JDK binary images, nor will it introduce a module system. That work will be covered by related JEPs and, where appropriate, JSRs.

This JEP will define a new source-code layout for the JDK. This layout may be used outside of the JDK, but it is not a goal of this JEP to design a broadly-accepted universal modular source-code layout.


Project Jigsaw aims to design and implement a standard module system for the Java SE Platform and to apply that system to the Platform itself, and to the JDK. Its primary goals are to make implementations of the Platform more easily scalable down to small devices, improve security and maintainability, enable improved application performance, and provide developers with better tools for programming in the large.

This JEP is the first step of Project Jigsaw; later JEPs will modularize the JRE and JDK images (JEP 220) and then introduce a module system (JEP 261).

The motivations to reorganize the source code at this early stage are to:

  1. Give JDK developers the opportunity to become familiar with the modular structure of the system;

  2. Preserve that structure going forward by enforcing module boundaries in the build, even prior to the introduction of a module system; and

  3. Enable further development of Project Jigsaw to proceed without always having to "shuffle" the present non-modular source code into modular form.


Current scheme

Most of the JDK source code is today organized, roughly, in a scheme that dates back to 1997. In abbreviated form:



To take a simple example, the source code for the java.lang.Object class in the jdk repository resides in two files, one in Java and the other in C:


For a less trivial example, the source code for the package-private java.lang.ProcessImpl and ProcessEnvironment classes is operating-system-specific; for Unix-like systems it resides in three files:


(Yes, the second-level directory is named solaris even though this code is relevant to all Unix derivatives; more on this below.)

There are a handful of directories under src/{share,$OS} that don't match the current structure, including:

Directory                     Content
--------------------------    --------------------------
src/{share,$OS}/back          JDWP back end
                bin           Java launcher
                instrument    Instrumentation support
                javavm        Exported JVM include files
                lib           Files for $JAVA_HOME/lib
                transport     JDWP transports

New scheme

The modularization of the JDK presents a rare opportunity to completely restructure the source code in order to make it easier to maintain. We propose to implement the following scheme in every repository in the JDK forest except for hotspot. In abbreviated form:



To recast the previous examples, the source code for the java.lang.Object class will be laid out as follows:


The source code for the package-private java.lang.ProcessImpl and ProcessEnvironment classes will be laid out this way:


(We take the opportunity here, finally, to rename the solaris directory to unix.)

The content of the directories currently under src/{share,$OS} that don't match the current structure will be moved into appropriate modules:

Directory                     Module
--------------------------    --------------------------
src/{share,$OS}/back          jdk.jdwp.agent
                bin           java.base
                instrument    java.instrument
                javavm        java.base
                lib           $MODULE/{share,$OS}/conf
                transport     jdk.jdwp.agent

Files in the current lib directory that are not intended to be edited by end users will be converted into resource files.

Build-system changes

The build system will be modified to compile one module at a time rather than one repository at a time, and it will compile modules according to a reverse topological sort of the module graph. Modules that do not depend on each other, directly or indirectly, will be compiled concurrently when possible.

A side benefit of compiling modules rather than repositories is that code in the corba, jaxp, and jaxws repositories will be able to make use of new Java language features and APIs. This was previously forbidden, since those repositories were compiled before the jdk repository.

The compiled classes in an intermediate (i.e., non-image) build will be divided into modules. Where today we have:


the revised build system will produce:


The structure of image builds, as noted, will not change; there will be very minor differences in their content.

Module boundaries will be enforced at build time, insofar as possible, by the build system. If a module boundary is violated then the build will fail. The boundaries will be defined in the modules.xml file described in JEP 200, which will be maintained alongside the source code. Changes to this file will require review by Committers to Project Jigsaw.


There are numerous other possible source-layout schemes, including:

  1. Keep {share,$OS} at the top, with a modules directory to contain module class files:

  2. Put everything under the appropriate $MODULE directory, but keep {share,$OS} at the top:

  3. Push {share,$OS} down into the $MODULE directories, as in the present proposal, but remove the intermediate classes directory and prefix the names of the native and conf directories with an underscore, all so as to simplify the common case of pure Java modules:

  4. A variant of scheme 3, but with {share,$OS} at the top:

  5. Another variant of scheme 3, pushing {share,$OS} deeper down so as to further simplify the case of pure Java modules with no $OS-specific code:


We rejected the schemes involving underscores (3–5) as too unfamiliar and difficult to navigate. We prefer the present proposal over schemes 1 and 2 because it entails the least change from the current scheme while placing all of the source code for a module under a single directory. Tools and scripts that depend upon the current scheme must be revised, but at least for Java source code the structure underneath each $MODULE directory is the same as before.

Additional issues which we considered:


As stated, this JEP will not change the structure of the JRE and JDK binary images, and will make only minor changes to the content. We can therefore validate this change by comparing images built with it against images built without it, and running tests to validate the actual minor changes.

Risks and Assumptions

We assume that Mercurial will be able to handle the massive number of file-rename operations that will be done to implement this change, and to preserve all historical information in the process. Early testing has shown Mercurial to be capable of this, but there is still a minor risk that the relationship between the new and old locations of a file will not properly be recorded. In that case the history of the file in its old location will still be in the repository; it will just be more difficult to find.

It will be impossible to apply a patch created against a repository using the old scheme directly to a repository using the new scheme, and vice versa. To mitigate this we plan to develop a script to translate the file names in a patch from their old locations to their new locations.


This JEP is the second of several JEPs for Project Jigsaw. It incorporates the definition of the modular structure of the JDK from JEP 200, but it does not explicitly depend upon that JEP.