The Top-Down Migration Strategy
What you'll learn: How to migrate to JPMS by modularizing your application code first while leaving external dependencies as automatic modules on the classpath.
The Strategy Explained
The top-down migration strategy is the opposite of bottom-up: you start by converting your own application code into explicit modules, while external libraries and dependencies remain on the classpath or module path as automatic modules.
Think of it like renovating a house from the roof down—you modernize the parts you control (your application's layers) while the foundation (third-party libraries) remains unchanged temporarily. The JVM treats JARs on the module path without a module-info.java as automatic modules, giving them module names derived from their filenames and allowing them to read all other modules.
How It Works
- Create
module-info.javafor your application modules with appropriaterequires,exports, and other directives - Place third-party JARs on the module path without modifying them—they become automatic modules
- Your modules
requirethese automatic modules by their derived names (typically the JAR name minus version numbers) - Gradually migrate dependencies as they release modular versions or as you have time to modularize them yourself
This approach lets you gain strong encapsulation benefits for your code immediately without waiting for the entire ecosystem to become modular. You control your API boundaries while maintaining compatibility with non-modular dependencies.
When to Use Top-Down
This strategy works best when you trust your application architecture and want to enforce module boundaries within your codebase, even if external libraries aren't yet modular. It's ideal for greenfield projects or applications with clear layering.
Key Takeaway: Top-down migration modularizes your application first while dependencies remain as automatic modules, giving you immediate encapsulation benefits for the code you control.