Java 9 Modules: Finally Some Structure

Java 9 modules land with a simple promise: real fences for our code.

If you have shipped large Java apps, you know the drill. The classpath is a mystery box, private stuff leaks out, and a tiny bump in a jar can wake the pager. Project Jigsaw has been years in the making, and it is finally close. The JCP just gave the spec a green light after some heated talk. We now get a standard way to say what we need and what we expose. No more public by accident. No more friends only by a comment on top of a class. We write it down in one place and the compiler enforces it.

Meet the module descriptor: a tiny file named module-info.java at the root of your source. It lists what you export and what you require. That is it. The VM knows your module name, your edges, and what stays inside. The rest is sealed off with strong encapsulation. Reflection cannot sneak into non exported packages unless you open a door. Here is a small sample for a library that ships a public API and hides the rest:

module-info.java

module com.acme.catalog {
    exports com.acme.catalog.api;
    requires java.sql;
}

If you want a dependency to leak through your API, mark it as requires transitive. That way callers of your module see it without adding it on their own. You can also wire services with uses and provides. The ideas are simple and they map to real needs, like plug a payment driver or a search engine that lives behind a clean contract. Here is a quick service setup:

Service API

// com.acme.payment.api
package com.acme.payment.api;
public interface PaymentGateway {
    boolean charge(String account, long cents);
}

Descriptor for the API module

module com.acme.payment.api {
    exports com.acme.payment.api;
    uses com.acme.payment.api.PaymentGateway;
}

Provider module

// com.acme.payment.stripe
module com.acme.payment.stripe {
    requires com.acme.payment.api;
    provides com.acme.payment.api.PaymentGateway
        with com.acme.payment.stripe.StripeGateway;
}

On the app side you ask the ServiceLoader for a PaymentGateway and you get whatever providers are present. No more hand rolled registries. It reads clean, and you can swap pieces during tests without fights.

Migration is the part everyone is poking. You do not need to modularize the whole world on day one. You can run on the module path with plain jars. Each plain jar becomes an automatic module with a name derived from the file. Your app still works, and you can move one module at a time. Watch for split packages since the system does not like the same package spread across modules. If you use deep reflection on internals, add opens for those packages, or make the entire module open while you clean things up. Try to keep that as a short bridge and not the default.

Tooling is catching up fast. IDE builds are already poking the module path. jdeps can tell you who touches what, which helps to carve the first descriptors. The new jlink tool lets you compose a small runtime that carries only the standard modules you need. For a microservice or a tiny desktop app, that trims the size and boots faster. Ship a single folder with your app and a runtime that fits it, and leave the rest behind. That alone can cut noise from support tickets.

My favorite side effect is readability. A module is a story. One file says what I offer, what I consume, and where my edges sit. Juniors can open a project and get the map in a minute. Seniors can refactor guts without fear that a random package gets imported from the other side of the codebase. It nudges teams to think in clear shapes and to stop treating private things as public just because it was easy.

We are not done as a community. Build tools are still smoothing things out. Some popular libs will need a tweak or two. But the core is here, and it feels sane. Start with one module. Add a descriptor. Export only what you must. Push the rest behind the fence. Little by little, your app starts to breathe.

Project Jigsaw gives Java a shared language for boundaries. That is long overdue, and it will pay off in cleaner APIs, smaller runtimes, and code you can actually reason about on a Monday morning.

Ship smaller runtimes.

Read your code like a table of contents.