Examine modular code development with Java's Project Jigsaw

The first release of Project Jigsaw is available for download, and what better way to celebrate its availability than to explore the downloadable files and see just how easy it is to create modular code using this new JCP standard?

To test the veracity of the downloaded project, the first step is to extract the contents of the compressed file to a convenient place on your computer's hard drive. Then download the file I created by following the Jigsaw Project's quick start guide's instructions. Figure 1 describes my .zip file's contents.

Figure 1. A description of the .zip file's contents.

Here are some observations about the .zip file's contents:

The file contains two samples:

• The first sample contains files and folders to run the smallest possible Project Jigsaw example. So small is this example that it contains no dependencies. It's a modular app consisting of only one module -- the com.greetings module.
• The second sample contains files and folders to run a simple app in which one module depends on another module. The com.greetings module depends on the org.astro module.

In each sample:

• The src folder contains the .java files
• The other folder (the mods folder) is destined to store the result of the compilation (the .class files)

In addition to the usual .java source files, each src file contains a new module-info.java file. The module-info.java file tells the new Project Jigsaw system how the modules are structured.

The module-info.java file for the first sample contains only one line:

The first sample's conventional Java code is an ordinary Hello World program:

The second sample's module-info.java files describe the dependency between the com.greetings and org.astro modules. Here's the org.astro project's module-info.java file:

And here's the com.greetings project's module-info.java file:

When you look at the code in the second sample's Main.java and World.java files, you can see why the com.greetings module depends on the org.astro module. Here's the org.astro module's World.java file:

And here's the com.greetings module's Main.java file:

To compile an example, you specify the new module-info.java file as well as the conventional .java files. For example, to compile the independent greeting program in sample1, I defined the sample1 directory as my working directory. Then I typed the following command (all on one line):

This command ..\..\jdk1.9.0 refers to the location of the newly downloaded Jigsaw-enabled JDK on my computer's hard drive. The javac command where to place the .class files. (Note how I put them in a .java references point to the .java files that are being compiled (including the new module-info.java file).

To run your own test, change my .java..\..\jdk1.9.0\ reference to the name of the folder where you've extracted the Project Jigsaw early release download on your computer's hard drive. For example, on my Mac, I type the following command (all on one line):

When you compile the World.java file in sample2, you do more or less the same thing:

Neither the sample1 Main class nor the sample2 World class depends on any other class's code, so the commands to compile these classes are very simple.

But when you compile a module that depends on other modules, you add the -modulepath switch to the javac command. For example, after you've compiled the org.astro module in sample2, you compile the sample2 version of the com.greetings module:

In this command, the enhanced -modulepath switch tells javac that any modules on which this compilation depends live in the mods folder. And indeed, in Figure 1, the sample2 project's mods folder contains an org.astro subfolder. This org.astro subfolder contains the .class files that come from having compiled the org.astro module.

Figure 2 shows what you have after you've compiled sample1 and sample2. You have newly created .class files in the mods folders. This includes some .class files created from the module-info.java files.

Figure 2. The results of compiling sample1 and sample2.

When you run a Jigsaw-enabled project, you add a -modulepath switch to a run with the java command. You also add an -m switch (where -m is short for -modulename):

The -modulepath switch tells the java command where to look for dependencies, and the -m switch tells java which module to run.

Figure 3. Commands used to compile and run sample1.

If you haven't been keeping score, Figure 3 has a summary of the commands that I use to compile and run sample1.  Figure 4 shows the commands that I use to compile and run sample2.

Figure 4. Commands used to compile and run sample2.

Project Jigsaw is much more than one or two Hello World programs. When it's released in September 2016, Project Jigsaw will be a new way of modularizing Java projects and a new way of modularizing the entire Java API. For an in-depth look at Project Jigsaw, visit the main project page at OpenJDK.java.net.

How will Project Jigsaw change the way you develop modular code? Let us know.