Java Module System Quick-Start Guide

This repository is based on Project Jigsaw's Module System Quick-Start Guide. The sections there have been reworked here into a series of commits and runnable code, each demonstrating a key aspect of Java's new module system.

Along the way, you'll transform a traditional Java main class into a Java module that makes use of all the major features Jigsaw has to offer. Each step can be run using the step.sh script, but the steps can also simply be read in order using git log. See below for instructions on both approaches.

How to use this guide

The commits in this repository are meant to be read in order like a tutorial, and the best way to do that is at the command line on your local machine.

First, clone the repo:

$ git clone https://github.com/cbeams/jigsaw-quick-start.git
$ cd jigsaw-quick-start

Then set up these two git aliases:

$ git config alias.steps 'log --oneline --reverse step0^..step7'
$ git config alias.read 'log -p --reverse step0^..step7'

The first alias, git steps shows you an overview of each step in the guide:

$ git steps
c7facdc (tag: step0) Introduce com.greetings package and main class
b4dbc1a (tag: step1) Transform com.greetings source into a Java module
7f62b33 (tag: step2) Assemble com.greetings into executable modular jar
f131a70 (tag: step3) Introduce org.astro module dependency
bdb74ae (tag: step4) Remove requires statement and fail at compile time
cccaaab (tag: step5) Remove exports statement and fail at compile time
96cff2b Revert introduction of the org.astro module
7b3c7d1 (tag: step6) Introduce SPI without provider and fail at runtime
a5db24c (tag: step7) Introduce service provider and bind successfully

The second alias, git read displays the log of each commit, in order, including both comment and patch. This allows you to see exactly what changes in each step and why:

$ git read
commit c7facdca5d51370ef6a6df8725279eaec3c872d2 (tag: step0)
Author: Chris Beams <[email protected]>
Date:   Tue Oct 13 16:09:44 2015 +0200

    Introduce com.greetings package and main class

    This step adds a simple main class, compiles it with javac and runs it
    with java in the usual fashion. No Jigsaw and no modules yet; that will
    come in the next step.

    When this step is run, it should print the following to the console:

        $ ./step.sh
        Greetings from main!

    See http://openjdk.java.net/projects/jigsaw/quick-start#greeting

diff --git src/com.greetings/com/greetings/Main.java
new file mode 100644
index 0000000..4f5991f
--- /dev/null
+++ src/com.greetings/com/greetings/Main.java
@@ -0,0 +1,9 @@
+package com.greetings;
+
+public class Main {
+
+    public static void main(String[] args) {
+        Object name = "main";
+        System.out.format("Greetings from %s!\n", name);
+    }
+}
diff --git step.sh step.sh
index 59bf8a3..b20a0fe 100755
--- step.sh
+++ step.sh
@@ -7,9 +7,12 @@ cat << task

 task
 (rm -rf bin && mkdir bin) || exit
-echo '(nothing to compile yet)'
+mkdir bin/com.greetings
 set -x

+javac -d bin/com.greetings \
+    $(find src/com.greetings -name '*.java') || exit
+
 find bin -type f

@@ -30,5 +33,8 @@ cat << task
     Run

 task
-echo '(nothing to run yet)'
 set -x
+
+java \
+    -classpath bin/com.greetings \
+    com.greetings.Main

commit b4dbc1ab8cc23dc64aabdf6e79cb491ba6546407 (tag: step1)
Author: Chris Beams <[email protected]>
Date:   Thu Oct 8 16:12:50 2015 +0200

    Transform com.greetings source into a Java module

    This step transforms the existing `com.greetings` source into a Java
    module simply by introducing an empty `module-info.java` file at the
    source directory root.

    With this _module declaration_ file in place and compiled along with the
    rest of the sources, `java` can now be invoked with its new `--module-path`
    option as opposed to the traditional `-classpath` option. Note how the
    modulepath now need only contain the top-level `bin` output directory,
    while the path to the main class (the new `-m` option) needs to be fully
    qualified by both module and package.

    When this step is run, the output should remain the same as the previous
    step. Nothing has changed in the program itself; only how the compiled
    artifacts are structured and invoked has changed:

        $ ./step.sh
        Greetings from main!

    See http://openjdk.java.net/projects/jigsaw/quick-start#greetings

diff --git src/com.greetings/module-info.java
new file mode 100644
index 0000000..4a27728
--- /dev/null
+++ src/com.greetings/module-info.java
@@ -0,0 +1,2 @@
+module com.greetings {
+}
diff --git step.sh step.sh
index b20a0fe..37b0c9f 100755
--- step.sh
+++ step.sh
@@ -36,5 +36,5 @@ task
 set -x

 java \
-    -classpath bin/com.greetings \
-    com.greetings.Main
+    --module-path bin \
+    -m com.greetings/com.greetings.Main

Run the steps

The step.sh script is present at each step in the guide, and you can run it to see Jigsaw in action.

To do this, you'll first need a JDK 9 early access build that includes project Jigsaw. Build 111 or better will work.

Once properly installed, java -version should tell you something like this:

$ java -version
java version "9-ea"
Java(TM) SE Runtime Environment (build 9-ea+111-2016-03-30-170352.javare.4768.nc)
Java HotSpot(TM) 64-Bit Server VM (build 9-ea+111-2016-03-30-170352.javare.4768.nc, mixed mode)

At this point you're ready to run through each step using the following commands:

1. Check out a step

   $ git checkout step0
   

2. Read the commit to understand what's changed

   $ git show
   

3. Run the demo script to see it all in action

   $ ./step.sh
   

then repeat for each of the remaining steps

$ git checkout step1
$ git show
$ ./step.sh
...

and remember to use git steps as a table of contents if you want to jump around.