Java Academy · Lesson

Migrating to Modules

Automatic and unnamed modules.

Migrating to Modules is a free Java Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Java Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Modularizing Existing Code

Few projects adopt modules from day one. JPMS was designed for gradual migration, letting classpath and module path coexist.

The keys are automatic modules and the unnamed module.

The Unnamed Module

Everything loaded from the classpath lives in the single unnamed module. It reads every other module and exports all its packages.

This is the bridge that keeps legacy classpath code working.

Named Cannot Read Unnamed

A crucial rule: an explicit named module cannot depend on the unnamed module. You cannot write requires for classpath code.

So you migrate bottom-up: convert your dependencies' representation first.

Automatic Modules

Put a plain (non-modular) JAR on the module path and it becomes an automatic module. It gets an auto-derived name, reads all other modules, and exports all its packages.

This lets named modules requires a JAR that has no module-info yet.

Where the Name Comes From

An automatic module's name is derived in order of preference:

The Automatic-Module-Name entry in the JAR manifest, if present
Otherwise from the JAR filename (version stripped, hyphens to dots)

Stable Names Matter

Library authors should add Automatic-Module-Name to their manifest before fully modularizing. It promises a stable module name so downstream requires clauses survive the eventual real module-info.

Automatic-Module-Name: com.example.json

Top-Down Strategy

The recommended approach for your own application:

Keep dependencies as automatic modules on the module path
Add a module-info.java to your top module first
Declare requires on those automatic module names

Example Migration Step

Suppose guava-32.jar sits on the module path as automatic module com.google.common. Your app module can already require it.

module com.example.app {
    requires com.google.common;
    exports com.example.app.api;
}

Split Packages Problem

The module system forbids two modules from containing the same package. Old libraries that split a package across JARs cause errors.

Fix by merging the JARs, using --patch-module, or upgrading to versions that resolve the split.

Reflection Access Issues

Frameworks doing deep reflection may fail with InaccessibleObjectException once you modularize. Add opens directives or, as a temporary bridge, the --add-opens launch flag.

Helpful jdeps Tool

The jdeps tool analyzes your JARs, reports dependencies, flags uses of internal JDK APIs, and can even generate a candidate module-info.java with jdeps --generate-module-info.

Run it first to plan your migration.

Quick Check

Recall how a plain JAR gains a module identity.

Recap

You learned migration techniques:

Classpath code lives in the unnamed module; named modules cannot require it
Plain JARs on the module path become automatic modules
Set Automatic-Module-Name for stable names
Watch for split packages and reflection access; use jdeps to plan

That completes the JPMS course.

Frequently asked questions

Is the “Migrating to Modules” lesson free?

Yes — the full text of “Migrating to Modules” is free to read here on the web, and the Java Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Java Academy course, upgrade to CoddyKit PRO.

What will I learn in “Migrating to Modules”?

Automatic and unnamed modules. You practise Java Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Java Academy?

No prior experience is required. Java Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Migrating to Modules” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Java Academy lesson?

Yes. Every Java Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Java Academy