Example example_splitpackage

Part of the full Java 9 Jigsaw modules example suite.

Authors

Originally written by Martin Lehmann, Kristine Schaal and Rüdiger Grammes (cf. original repository).

Migrated for Java Modules support documentation of Apache MavenTM in the course of the Maven Support & Care program by Gerd Aschemann (and other team members) as forked repository. Please add discussions, requirements, bugfixes, etc. to the fork instead of the original.

What is this example about?

Modules in this example

  • modb, modmain, modmainbar, modsplitbar1, modsplitbar2, modmainfoo, modsplitfoo1, modsplitfoo2

  • modmain has a Main class which is started in run.sh

Module Dependency Graph, created with DepVis

Example’s Module Dependency Graph

Example shows …​

Case 1)

  • modsplitfoo1 and modsplitfoo2 do both contain a package called pkgfoo.

  • modmainfoo requires modsplitfoo1 and modsplitfoo2 Does not compile! A module must not requires 2 or more modules, which have/export the same package

Case 2)

  • modsplitbar1 and modsplitbar2 do both contain a package called pkgbar (not exported).

  • modmainbar requires modsplitbar1

  • During runtime, --add-modules is used to load also modsplitbar2 Shows a runtime exception: In one classloader, two or more modules must not be loaded, which have/export the same package.

TODOs

  • Does case 2 work, if the classloader for modsplitbar1 and modsplitbar2 is different (i.e., what about layers)?

Maven 4 Migration

This example has been migrated to Maven 4 using the Module Source Hierarchy layout. The migration demonstrates an important constraint of the split package problem.

Migration Approach

Only bar modules are compiled in the Maven 4 migration:

  • modmainbar - Main module that requires modsplitbar1

  • modsplitbar1 - First module with package pkgbar

  • modsplitbar2 - Second module with package pkgbar

The foo modules (modmainfoo, modsplitfoo1, modsplitfoo2) cannot be compiled because modmainfoo requires both modsplitfoo1 and modsplitfoo2, which both export package pkgfoo. This violates Java Module rules at compile time.

Golden Master Testing

To maintain consistency with the original example, the Maven 4 run.sh script produces the same output format:

  1. First outputs: "Error: Does not run, as it does not even compile!" (representing the foo modules)

  2. Then runs the bar modules to demonstrate the runtime split package problem

This ensures the Maven 4 migration verifies against the same shared expected-result/run.txt as the original example.

Technical Implementation

The migration uses symbolic links to adapt the source structure to Maven 4’s Module Source Hierarchy:

m4/src/modmainbar/main/java -> ../../../../src/modmainbar
m4/src/modsplitbar1/main/java -> ../../../../src/modsplitbar1
m4/src/modsplitbar2/main/java -> ../../../../src/modsplitbar2

These symbolic links are checked into Git and do not need to be created dynamically.

The pom.xml declares these modules using Maven 4.1.0 model:

<sources>
  <source>
    <module>modmainbar</module>
    <directory>src/modmainbar/main/java</directory>
  </source>
  <source>
    <module>modsplitbar1</module>
    <directory>src/modsplitbar1/main/java</directory>
  </source>
  <source>
    <module>modsplitbar2</module>
    <directory>src/modsplitbar2/main/java</directory>
  </source>
</sources>

Running the Maven 4 Version

cd m4/
./compile.sh  # Compiles all bar modules, creates JARs
./run.sh      # Demonstrates both successful and failing cases
./verify.sh   # Verifies output matches expected result
./clean.sh    # Removes build artifacts and symbolic links

Output

This example uses golden master testing to ensure output consistency. The expected output is compared with actual output using verify.sh.

Expected Output

Error: Does not run, as it does not even compile!

Main: pkgmainbar.Main, id=ID_Main_13
Error occurred during initialization of boot layer
java.lang.LayerInstantiationException: Package pkgbar in two different modules

Actual Output

Error: Does not run, as it does not even compile!

Main: pkgmainbar.Main, id=ID_Main_13
Error occurred during initialization of boot layer
java.lang.LayerInstantiationException: Package pkgbar in two different modules

Maven 4 Output

Error: Does not run, as it does not even compile!

Main: pkgmainbar.Main, id=ID_Main_13
Error occurred during initialization of boot layer
java.lang.LayerInstantiationException: Package pkgbar in two different modules