Course contentsShow
← Java
Lesson 2528 of 2,87047. Java Platform Module System (JPMS)Free lesson

Handling Split Packages Across Dependencies

Understand why split packages prevent modularization and learn strategies to resolve them through repackaging or merging.

Handling Split Packages Across Dependencies

You'll learn how to identify and resolve split package conflicts that block modularization.

The Core Problem

A split package occurs when two or more JARs (or modules) contain classes in the same package. For example, if library-a.jar and library-b.jar both define classes in com.example.util, that's a split package.

JPMS forbids split packages because modules enforce strong encapsulation at the package level. The module system can't determine which module "owns" a package when multiple modules claim it. This ambiguity breaks the readability and accessibility rules that make JPMS work.

Think of it like two different authors trying to write different chapters with the exact same chapter number in the same book—the reader can't know which chapter to read.

Why This Happens in Dependencies

Split packages often arise from:

  • Legacy libraries that were designed before JPMS
  • Different versions of the same library accidentally on the path
  • Companies creating multiple JARs that share package namespaces

Resolution Strategies

1. Repackaging

Relocate classes from one or both dependencies into unique packages. If you control the source, change the package names. If using build tools like Maven Shade or Gradle Shadow, you can automatically repackage third-party dependencies.

2. Merging

Combine the split JARs into a single modular JAR that exports the shared package once. This is feasible when both JARs are under your control or when they're logically part of the same module.

3. Classpath Workaround

As a temporary measure during migration, keep problematic JARs on the classpath (not module path) where split packages are tolerated, while modularizing the rest of your application.

Key Takeaway:
Split packages prevent modularization because JPMS requires unique package ownership; resolve them by repackaging classes into distinct packages, merging JARs, or temporarily using the classpath during migration.