Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 41 ยท Projects

Project: A Multi-Module Application

Build a three-module Maven application with a parent POM, managed versions, a BOM import and a runnable jar, and watch the reactor order and classpath.

A single module is fine for a library. Real applications split into layers so that each layer has its own dependencies and its own tests. In this project you will build a small shop application with three modules: shop-core (plain domain code), shop-service (business logic that uses Jackson) and shop-app (the entry point, packaged as a runnable jar). One parent POM ties them together.

You have met the ingredients separately: multi-module builds and the reactor, parent POMs, dependencyManagement and BOMs and packaging. Here you put them to work. Maven cannot run on this site, so the POMs and commands are read-only. Two TryIts simulate the reactor ordering and the classpath calculation.

Three modules, one parent

shop-core Domain types, no framework.
shop-service Business logic, uses Jackson.
shop-app Main class, runnable jar.
shop-parent Shared versions and settings.
1 / 2

The layout

TEXT
shop/
  pom.xml                  (shop-parent, packaging pom)
  shop-core/pom.xml
  shop-service/pom.xml
  shop-app/pom.xml

Each module is an ordinary Maven project in its own folder, with its own src/main/java and src/test/java. The top-level pom.xml has <packaging>pom</packaging>: it produces no jar, only configuration and the list of modules.

The parent POM

The parent does three jobs. It lists the modules, it sets build properties once and it decides every dependency version in one place.

XML
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.shop</groupId>
  <artifactId>shop-parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <modules>
    <module>shop-core</module>
    <module>shop-service</module>
    <module>shop-app</module>
  </modules>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <jackson.version>2.18.2</jackson.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <!-- BOM import: Jackson decides the versions of all its artifacts -->
      <dependency>
        <groupId>com.fasterxml.jackson</groupId>
        <artifactId>jackson-bom</artifactId>
        <version>${jackson.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

      <!-- Our own modules, all at the parent's version -->
      <dependency>
        <groupId>com.example.shop</groupId>
        <artifactId>shop-core</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>com.example.shop</groupId>
        <artifactId>shop-service</artifactId>
        <version>${project.version}</version>
      </dependency>

      <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.11.4</version>
        <scope>test</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

dependencyManagement declares versions without adding anything to any classpath. A module only gets a library when it lists it in its own <dependencies>, and then it may omit the version. The import scope pulls in Jackson's BOM, so jackson-databind, jackson-core and jackson-annotations always share one version, which avoids the mismatches described in Diagnosing Dependency Conflicts. The module entries use ${project.version}, so bumping the parent version bumps all module-to-module links at once.

The modules

shop-core has the simplest POM. It points at the parent and has no dependencies of its own. The groupId and version are inherited, so only the artifactId is needed:

XML
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example.shop</groupId>
    <artifactId>shop-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>
  <artifactId>shop-core</artifactId>
</project>

shop-service depends on shop-core and Jackson, and tests with JUnit. Notice there is no <version> anywhere in its dependency list:

XML
<dependencies>
  <dependency>
    <groupId>com.example.shop</groupId>
    <artifactId>shop-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
  </dependency>
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

shop-app depends on shop-service and carries the build configuration for the runnable jar. The Shade plugin merges the module and all its runtime dependencies into one jar and writes the Main-Class entry into the manifest:

XML
<dependencies>
  <dependency>
    <groupId>com.example.shop</groupId>
    <artifactId>shop-service</artifactId>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>3.6.0</version>
      <executions>
        <execution>
          <phase>package</phase>
          <goals><goal>shade</goal></goals>
          <configuration>
            <transformers>
              <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                <mainClass>com.example.shop.app.Main</mainClass>
              </transformer>
            </transformers>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Because shop-app never mentions shop-core or Jackson, they arrive as transitive dependencies through shop-service. If shop-app calls shop-core classes directly, declare that dependency explicitly anyway: relying on transitive arrival makes the build fragile when shop-service changes.

Building and running

Terminal
mvn package                                   # build everything, in reactor order
java -jar shop-app/target/shop-app-1.0.0-SNAPSHOT.jar

mvn -pl shop-service -am test                 # one module plus what it needs
mvn -pl shop-core -amd package                # one module plus everything that needs it

-pl (projects) selects modules, -am (also make) adds the modules they depend on, and -amd (also make dependents) adds the modules that depend on them. Without -am, mvn -pl shop-app package would fail on a fresh checkout, because shop-service is not built and not yet in your local repository.

Reactor order

Maven does not build modules in the order of <modules>. It sorts them so that every module comes after the modules it needs, including its parent. The listing order only breaks ties. A cycle makes the sort impossible, and Maven refuses to build.

The first TryIt is a stand-in for that sorting step. It uses a depth-first topological sort, applies -am and -amd as set operations over the graph, and then adds a forbidden dependency from core back to the app to show the cycle error.

Java Reactor order, -am, -amd and a cycle

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Classpath calculation

Each module gets its own classpath, computed from its dependencies and their scopes. The rules from Dependency Scopes apply: a module sees compile, provided, runtime and test dependencies it declares itself, but only the compile and runtime dependencies of its dependencies. A test dependency of shop-service never leaks into shop-app.

The second TryIt computes both a runtime classpath for the app and a test classpath for the service. Versions come from a managed-version table, just like the parent's dependencyManagement.

Java Classpaths with managed versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check the output against the explanation above: JUnit appears only in the service's test classpath, never in the app's runtime classpath, and Jackson's three artifacts carry the same version because one managed entry decides it.

Common mistakes

  • Versions scattered across modules. If two modules each pin their own Jackson version, the one that wins depends on mediation. Manage versions in the parent.
  • Using <modules> order as build order. It is only a tie-breaker.
  • Forgetting -am. Selecting one module with -pl on a clean machine fails when its sibling modules are not installed.
  • Putting application plugins in the parent's <build>. Every module would then try to shade a jar. Use pluginManagement in the parent and activate the plugin only in shop-app.
  • Aggregation and inheritance are different things. The parent lists modules (aggregation) and each module names its parent (inheritance). They usually coincide but need not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should the Jackson version for all modules be decided?

    dependencyManagement in the parent gives one decision point; the BOM keeps all Jackson artifacts on a matching version.
  2. 2. You run 'mvn -pl shop-app package' on a fresh clone and it fails to resolve shop-service. What is the fix?

    -am (also make) builds the upstream modules in the reactor, so shop-service exists even though it was never installed.
  3. 3. Does shop-service's junit-jupiter (test scope) appear on shop-app's runtime classpath?

    Test-scoped dependencies belong to the module that declares them and are never passed on to its consumers.
  4. 4. What does the reactor do when module A depends on B and B depends on A?

    A topological order cannot exist for a cycle, so Maven stops before building anything.

Summary

  • The parent POM (packaging pom) lists the modules, holds shared properties and manages every dependency version.
  • A BOM imported with import scope keeps a family of artifacts on one version; ${project.version} links sibling modules.
  • Child modules inherit groupId and version, and list dependencies without versions.
  • The reactor sorts modules by dependency, not by listing order; -pl, -am and -amd select parts of the build.
  • Test dependencies stay with their module. The POMs and commands are read-only, and the simulations are stand-ins for Maven's real resolver.

Next, automate the build: Project: A CI Pipeline for a Maven Project.