During a JPMS migration, what problems arise from automatic modules and split packages, and how do you reason about them?

## Setting the scene Large codebases adopt JPMS gradually, leaning on **automatic modules** (plain JARs on the module path) to bridge to not-yet-modular dependencies. That bridge has sharp edges, and a separate structural rule — **no split packages** — trips up legacy code. A principal engineer needs to reason about both and set policy. ## Hazard 1: automatic modules are deliberately leaky Recall what an automatic module *is*: a non-modular JAR given module status so a named module can `requires` it. To make that work without a descriptor, the runtime grants it two blanket permissions: - it **implicitly exports every package** (no encapsulation), and - it **implicitly reads every other module**, including the **unnamed module**. Consequences to reason about: 1. **No encapsulation.** Anything in the automatic module's JAR — including what the library author considers private internals — is exported and reachable. If your code (or a transitive consumer) starts depending on those internals, you've coupled to implementation detail that will *break* the day the library ships a real `module-info` that hides them. So a key rule is: **don't let your public API surface lean on an automatic module's leaked internals.** 2. **Unstable identity.** If the JAR lacks an `Automatic-Module-Name` manifest header, its name is derived from the **filename** (version stripped, non-alphanumerics to dots). Renames, mirror differences, or version-scheme quirks can change that name and break every `requires`. An illegal derived name (e.g. one starting with a digit) makes the JVM reject the JAR outright. 3. **It still sees the classpath.** Because automatic modules read the unnamed module, a half-migrated app keeps working — but this also means you can't rely on the dependency graph being fully validated; the automatic module can pull in anonymous classpath code that isn't represented in the module graph. **Policy stance:** treat automatic modules as a *temporary* state. Prefer dependencies that publish `Automatic-Module-Name` (stable name) and push toward those that publish a real `module-info` (true encapsulation). Where neither exists and the risk is high, repackage/shade the dependency under your own coordinates so you control its module identity and contents. ## Hazard 2: split packages JPMS enforces a structural invariant: **a given package may be defined in only one module** that a particular module reads. Two modules in the same readability scope contributing the *same* package is a **split package**, and the runtime rejects it. Why the rule exists: if package `com.foo` lived in two modules, the system couldn't unambiguously decide which module's classes you get, and the *reliable configuration* guarantee would collapse. So JPMS disallows it by construction. Where it bites in legacy code: - A library historically shipped as several JARs that all contribute classes to the same package (common before modularisation). - An old JAR redefines a package that the JDK itself now owns (e.g. some XML/`java.*`/`javax.*` packages that moved into platform modules). On the module path this collides with the platform module; you cannot just `requires` your way out. - 'Uber' shading that merges packages can also create or hide splits depending on how it's done. The errors surface during resolution (e.g. *'module X reads package P from both Y and Z'* or *'package P in both module A and the unnamed module'*). ## Reasoning about fixes (split packages) - **Merge** the split: combine the JARs that share a package into one module so the package has a single owner. - **Relocate (shade):** rename the offending package to a unique prefix at build time so it no longer collides. - **Exclude/replace:** drop the legacy JAR in favour of a maintained, modular replacement, or exclude the duplicated JDK-overlap package. - **As a last resort during transition:** keep the colliding pieces on the classpath (unnamed module) where the no-split rule isn't enforced — but accept you've then given up modular guarantees for them, and named modules still can't read them. ## Putting it together (the principal view) The through-line is that **automatic modules and the classpath are scaffolding, not a destination.** A sound migration: modularise top-down; depend on automatic modules only transitionally; never expose their leaked internals in your own APIs; demand stable `Automatic-Module-Name` from upstreams; and proactively hunt and eliminate split packages (merge/relocate/replace) so the module graph can be fully validated. The payoff is the JPMS guarantees the scaffolding was hiding: explicit, validated dependencies and genuine encapsulation.