Migration Challenges

## Background: modules and packages A **package** in Java is a namespace for classes, like `com.acme.util`. The **Java Platform Module System (JPMS)**, added in Java 9 (Project Jigsaw), introduces a layer above packages: a **module** is a named, self-describing unit declared by a `module-info.java` file that states what it `requires` (depends on) and `exports` (makes visible). Modules placed on the **module path** form a **module graph** that the runtime resolves at startup. ## What a split package is A **split package** exists when the *exact same package name* is contributed by **two or more modules** at the same time. Example: both `module-a` and `module-b` contain classes in package `javax.annotation`. ## Why JPMS forbids it JPMS guarantees **reliable configuration**: for any package, there is exactly one module that owns and can export it, so the runtime knows unambiguously where a type comes from. If two modules both claimed `javax.annotation`, the resolver could not decide which one a `requires` should read, and **strong encapsulation** (the rule that you can only see exported packages of modules you require) would be undefined. So the module system rejects the configuration at resolution time with an error such as `module X reads package javax.annotation from both Y and Z` or refuses to define two modules owning the same package. Note the contrast with the **classpath / unnamed module**: the classpath has *no* split-package check (it just uses first-wins class loading), which is one reason classpath apps tolerated overlapping jars for years. ## How splits arise during migration 1. **Legacy JSR jars** — many old API jars (annotations, JAXB, JAX-WS) re-declare `javax.*` packages that also exist elsewhere. 2. **Two versions of the same library** transitively pulled in. 3. **Drawing a module boundary** through a package — putting half of `com.acme.util` in one module and half in another. ## How to fix it - **Consolidate ownership** — merge the conflicting jars/classes so the package lives in exactly one module. - **Exclude the duplicate** — choose one canonical artifact (build-tool dependency exclusion) and drop the other. - **Relocate** — move classes so each package is whole in a single module (sometimes renaming the package). - **Stay on the classpath** — leaving the offending jars on the classpath (not the module path) sidesteps the check entirely during incremental migration. - **`--patch-module <module>=<jar/dir>`** — an escape hatch that injects extra classes into a named module at compile/run time, effectively healing a split for a known module; useful as a transition crutch, not a permanent design. ## Key takeaways Split packages are a *configuration* error, not a runtime crash deep in your code: the JVM refuses to start (or javac refuses to compile) when the module path has them. The durable fix is making each package owned by one module; the classpath and `--patch-module` are tactical workarounds during migration.