about this book

Java 9 introduced the Java Platform Module System (JPMS) to the language and ecosystem and made modularity primitives readily available to all Java developers. For most people, me included, these concepts are new, so this book teaches them from the ground up. It goes all the way from the motivation and basics to advanced features. More than that, it also helps you migrate your existing projects to Java 9+ as well as to incrementally modularize them if you want to do that.

Note that we do not set out to study modularity per se. This is a complex topic, and entire books have been written about it (for example, Java Application Architecture by Kirk Knoernschild [Prentice Hall, 2012]). But while we focus on putting modularity into action with the module system, you won’t be able to avoid learning about the reasons for doing so.

Who should read this book

The module system is an interesting beast. Its underlying principles and concepts are quite simple, yet its effects on the ecosystem aren’t. It’s not as immediately exciting as lambda expressions, but it will change the ecosystem just as thoroughly. In the end, all of that hardly matters, though. By now, it’s as much a part of Java as the compiler, the private modifier, and the if statement; and just as every developer needs to know those, they need to know about the module system.

Fortunately, getting started is easy. At the module system’s core lie just a few simple concepts that every developer with a minimum amount of Java knowledge can understand. Basically, you’re good to go if you know how visibility modifiers work; have a rough idea how to use javac, jar, and java; and know that the JVM loads classes from JARs.

If that describes you, and you like a challenge, I encourage you to read this book—you might not be able to connect all the dots, but you’ll still walk away with a strong understanding of the module system and a lot of things to follow up on to better understand the Java ecosystem.

To connect all the dots, on the other hand, you should have a couple of years of experience developing Java projects. Generally speaking, the larger they are and the more involved you are in evolving their architecture, picking the right dependencies, and fighting with them when they weren’t, the more you will appreciate what the module system has to offer. It will also be easier to vet the impact the module system has on your project and the ecosystem at large.

How this book is organized: a roadmap

The book is structured on several levels. It’s obviously split into chapters (and three parts), but it doesn’t require you to read them linearly, so I also have a couple of proposals for what to read in which order.

Parts and chapters

This book consists of 15 chapters, organized into 3 parts.

Part 1, “Hello, modules,” shows the Java shortcomings that the module system was created to overcome, and explains its basic mechanisms and how to create, build, and run modular applications:

• Chapter 1, “First piece of the puzzle,” discusses Java’s lack of support for modularity on the level of JARs, the negative effects that has, and how the module system will tackle these deficiencies.
• Chapter 2, “Anatomy of a modular application,” showcases how to build and run a modular application and introduces the example app that’s used throughout the book. This chapter gives you the big picture but doesn’t go into details—that’s what the next three chapters do.
• Chapter 3, “Defining modules and their properties,” introduces the module declaration as the basic building block of modules and how the module system processes it to achieve its most important goals: making projects more reliable and maintainable.
• Chapter 4, “Building modules from source to JAR,” shows how to compile and package a modular project with the javac and jar commands.
• Chapter 5, “Running and debugging modular applications,” examines the many new options on the java command. Launching a modular application is simple, so this chapter spends most of its time giving you the tools you need to find and solve problems.

Part 2, “Adapting real-world projects,” turns away from the ideal case of a fully modularized project and addresses how to migrate existing projects to Java 9+ and how to modularize them incrementally:

• Chapter 6, “Compatibility challenges when moving to Java 9 or later,” explores the most common hurdles you’ll face when migrating an existing code base to Java 9 (you’re not creating any modules yet).
• Chapter 7, “Recurring challenges when running on Java 9 or later,” discusses two more hurdles, which are set apart because they aren’t limited to migrations—you’re just as likely to face them even after you’ve migrated and modularized your project.
• Chapter 8, “Incremental modularization of existing projects,” shows how to take a large code base that runs on Java 9 and start turning it into modules. The good news is that you don’t have to do it all at once.
• Chapter 9, “Migration and modularization strategies,” reflects over the previous three chapters and develops strategies that help you migrate and modularize an existing code base.

Part 3, “Advanced module system features,” shows capabilities that build on the basics introduced in part 1:

• Chapter 10, “Using services to decouple modules,” shows how the module system supports the separation of consumers and implementers of an API.
• Chapter 11, “Refining dependencies and APIs,” extends the basic dependency and accessibility mechanisms introduced in chapter 3, giving you the flexibility you need to implement messy, real-world use cases.
• Chapter 12, “Reflection in a modular world,” discusses how reflection lost its superpowers; what application, library, and framework developers have to do to make reflecting code work; and which new, powerful features the reflection API was extended with.
• Chapter 13, “Module versions: What’s possible and what’s not,” explains why the module system mostly ignores version information, what little support it has for versions, and how it’s possible, albeit complex, to run several versions of the same module.
• Chapter 14, “Customizing runtime images with jlink,” shows how you can benefit from the modularized JDK by creating your own runtime images with just the modules you need and how you can benefit from a modularized application by including it in that image, giving you a single deployment unit.
• Chapter 15, “Putting the pieces together,” shows what the application introduced in chapter 2 looks like with all the bells and whistles from part 3. It also gives advice on how to best use the module system.

Pick your own path

I want this book to be more than just a one-off device that teaches you about the module system when you read it cover to cover. Not that there’s anything wrong with that, but I want it to be more. I want it to be your guide that you can use to learn what you care about the most in the order you’re interested and that can stay on your desk, ready to be used as a reference whenever you need to look up a detail.

So while you’re of course invited to read this book from beginning to end, you absolutely don’t have to. I made sure that each mechanism and feature gets its own chapter or section, so it’s introduced in all detail in one spot. If you need to read up on a concept, check the index—the page on which a term is first introduced is marked in bold.

To make jumping into a chapter easier, I often restate and cross-reference facts that are introduced in other parts of the book so that you’re aware of them if you haven’t read the corresponding part. I hope you forgive me if, at times, you feel that I’m repeating myself or putting up too many signposts.

In case you’re not a cover-to-cover person, here are a few paths you could take:

I have two hours—show me what you’ve got:

• “Goals of the module system,” section 1.5.
• “Anatomy of a modular application,” chapter 2.
• “Defining modules and their properties,” chapter 3.
• “Tips for a modular application,” section 15.2.

I want my existing project to run on Java 9:

• “First piece of the puzzle,” chapter 1.
• “Defining modules and their properties,” chapter 3.
• “Compatibility challenges when moving to Java 9 or later,” chapter 6.
• “Recurring challenges when running on Java 9 or later,” chapter 7.
• “The unnamed module, aka the class path,” section 8.2.
• “Migration strategies,” section 9.1.

I’m considering starting a new project with modules:

• “Hello, modules,” part 1.
• “Using services to decouple modules,” chapter 10.
• “Refining dependencies and APIs,” chapter 11.
• “Putting the pieces together,” chapter 15.

How does the module system change the Java ecosystem?

• “First piece of the puzzle,” chapter 1.
• “Anatomy of a modular application,” chapter 2.
• “Defining modules and their properties,” chapter 3.
• Skim “Compatibility challenges when moving to Java 9 or later,” chapter 6 and “Recurring challenges when running on Java 9 or later,” chapter 7.
• “Advanced module system features,” part 3, except possibly chapters 10 and 11.

I’m invited to a party and need to know some oddities of the module system to make conversation:

• “Bird’s-eye view of the module system,” section 1.4.
• “Goals of the module system,” section 1.5.
• “Organizing your project in a directory structure,” section 4.1.
• “Loading resources from modules,” section 5.2.
• “Debugging modules and modular applications,” section 5.3.
• Anything from “Compatibility challenges when moving to Java 9 or later,” chapter 6; and “Recurring challenges when running on Java 9 or later,” chapter 7 makes a great conversation starter.
• “Module versions: What’s possible and what’s not,” chapter 13.
• “Customizing runtime images with jlink,” chapter 14.

This is awesome. I want to know everything!

• Read everything. Maybe leave part 2, “Adapting real-world projects,” for the end if you don’t have an existing project to worry about.

Whichever path you take, look out for signposts, particularly at the beginning and end of each chapter, to decide where to go next.

Watch out for these

This book is full of new terms, examples, tips, and things to keep in mind. To make it easier for you to find what you’re looking for, I explicitly highlighted two kinds of information:

Definitions of a new concept, term, module property, or command-line option are in italics. The most important ones are set in a grey box with a header. All these are the most essential paragraphs in the book—search for them if you need to look up how exactly a specific mechanism works.

About the code

The entire book uses the ServiceMonitor application to demonstrate the module system’s features and behavior. You can find it at www.manning.com/books/the-java-module-system and also at https://github.com/CodeFX-org/demo-jpms-monitor.

In slight variations, it’s used in almost all chapters. The Git repository has a few branches that specifically show the features presented in part 1 (mostly master and a few of the break-... branches) and part 3 (separate feature-... and the other break-... branches).

Part 2, which tackles migration and modularization challenges, also occasionally uses ServiceMonitor as an example, but there are no specific branches for that. Another variant of the application showcases a couple of the migration problems, though: https://github.com/CodeFX-org/demo-java-9-migration.

All you need to code along with the book or experiment with the examples is Java 9 or later (see the next section), a text editor, and minimal command-line skills. If you decide to work with the code in an IDE, pick one that has proper Java 9 support (at least IntelliJ IDEA 2017.2, Eclipse Oxygen.1a, or NetBeans 9). I recommend either typing the commands yourself or running the .sh or .bat scripts, but for some use cases you can use Maven—if you want to build projects with it, you need at least 3.5.0.

You can find more setup details in each project’s README.

About the Java version

This book was written when Java 9 was still fresh, and all code is guaranteed to work on it—more precisely, on version 9.0.4. It has also been tested on and updated for Java 10 and 11. When the book was going to print, 11 was still in early access, though, and it’s possible that there will be small changes before the release that aren’t reflected in this book.

Java 9 not only introduced the module system, though; it was also the starting point of the six-month release cycle. So Java 10 and 11 are already out, and even Java 12 will be soon (depending on when you read this, it very well might already have been released). Does that mean this book is already dated?

Fortunately, not at all. Except for a few details, Java 10 and 11 don’t change anything about the module system; and even if we look further into the future, no major changes are planned. So while this book mostly mentions Java 9, all of that also applies to 10, 11, and probably a few more versions to come.

That’s particularly true for the compatibility challenges laid out in part 2. You can’t forego them by jumping from 8 to 10 or later. At the same time, once you’ve mastered Java 9, the rest will be a piece of cake, as Java 10 and 11 are much smaller releases with no compatibility problems.

Code formatting conventions

This book contains many examples of source code, both in numbered listings and in line with normal text. In both cases, source code is formatted in a fixed-width font like this to separate it from ordinary text. (Module names are italicized, though—see below.)

In many cases, the original source code and the compiler’s or JVM’s output have been reformatted to accommodate the available page space in the book:

• Added line breaks and reworked indentation
• Truncated output, for example by removing package names
• Shortened error messages

In rare cases, even this was not enough, and listings include line-continuation markers (➥). Additionally, comments in the source code have often been removed from the listings when the code is described in the text. Code annotations accompany many of the listings, highlighting important concepts.

Since Java 8, it’s common to use the method reference syntax to refer to methods on a class, so add on List is List::add. Unlike List.add, it doesn’t look similar to an actual method call (but where did the parenthesis go?) and doesn’t beg the question about the number of parameters. In fact List::add refers to all the add overloads, not just one of them. I use that syntax throughout the book.

Module name conventions

Because package and module names are so similar, I decided to italicize module names like so, whereas package names are in a fixed-width font. This lets you tell them apart, and I encourage you to use the same style if you write about modules.

Placeholders in code snippets

New features, like command-line flags and what goes into module-info.java, are defined in general terms. This makes it necessary to use ${placeholders} to point out where your specific values go. You can recognize them by the dollar sign, followed by curly braces.

This syntax is exclusively used in that context, and its similarity to how some operating systems and programming languages reference arguments or variables is not accidental. But it never refers to any specific mechanism, and placeholders are never meant to be filled in by the operating system or JVM. You will have to do that yourself, and you can usually spot an explanation of what to put into a ${placeholder} somewhere close by.

Example

From section 4.5.3:

When jar is used to package class files into an archive, it’s possible to define a main class with --main-class ${class}, where ${class} is the fully qualified name (meaning the package name appended with a dot and the class name) of the class with the main method.

Easy, right?

Commands and their output

The best way to get to know the module system is to use it directly by issuing javac, java, and other commands and read the messages Java prints back to the command line. Consequently, this book contains a lot of back and forth between commands and messages. In code snippets, commands are always prefixed with $, messages with >, and my comments with #.

Example

Here’s a command issued in section 5.3.2:

$ java
    --module-path mods
    --validate-modules

# truncated standardized Java modules
# truncated non-standardized JDK modules
> file:.../monitor.rest.jar monitor.rest
> file:.../monitor.observer.beta.jar monitor.observer.beta

liveBook discussion forum

Purchase of The Java Module System includes free access to a private web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the author and from other users. To access the forum, go to https://livebook.manning.com/#!/book/the-java-module-system/discussion. You can also learn more about Manning’s forums and the rules of conduct at https://livebook.manning.com/#!/discussion.

Manning’s commitment to our readers is to provide a venue where a meaningful dialogue between individual readers and between readers and the author can take place. It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the forum remains voluntary (and unpaid). We suggest you try asking the author some challenging questions lest his interest stray! The forum and the archives of previous discussions will be accessible from the publisher’s website as long as the book is in print.