What Does the Maven-Core Module Handle? A Deep Dive into Apache Maven's Build Engine

The maven-core module is the heart of Apache Maven, implementing the complete build lifecycle and providing the runtime engine that transforms a POM file into a built artifact.

The maven-core module serves as the central execution engine of the Apache Maven project. It bridges the gap between the command-line interface and the actual build process, handling everything from parsing project models to orchestrating plugin execution. While higher-level modules like maven-cli handle user interaction, they delegate the actual building work to the classes contained within maven-core.

Build Orchestration and Execution Entry Points

The maven-core module handles initial command-line parsing and creates a MavenExecutionRequest to represent the build intent. In impl/maven-core/src/main/java/org/apache/maven/Maven.java, the public API defines the primary entry point for executing a build. The concrete implementation resides in DefaultMaven.java, which drives the entire execution flow by creating the session and triggering the lifecycle.

Session Management and State Handling

Every build run maintains its state through the MavenSession class, located at impl/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java. This session object holds the current reactor, effective settings, and configuration for the execution. It provides the context that plugin Mojos and lifecycle participants access during the build.

Project Model Building and POM Resolution

The module reads pom.xml files and resolves parent POMs hierarchically through DefaultProjectBuilder.java in the internal implementation package. It aggregates multi-module projects and constructs the effective MavenProject model, resolving variables and applying profiles to produce the final project structure used throughout the build.

Reactor Construction and Dependency Graphs

For multi-module builds, the maven-core module constructs the directed dependency graph known as the reactor. Using ProjectDependencyGraph.java and DefaultProjectDependencyGraph.java, it detects cycles between modules and determines the correct execution order. The reactor ensures that dependencies are built before the projects that depend on them.

Lifecycle Execution and Plugin Management

The core maps lifecycle phases to plugin goals, resolves plugins from repositories, and creates MojoExecution instances. Key classes include MavenExecutionRequest.java, which represents the execution plan, and MojoExecution.java, which encapsulates a specific plugin goal to be invoked. The module ensures that Mojos execute in the correct phase order with proper dependency injection.

Event Handling and Extension Points

Through ExecutionListener.java and LoggingExecutionListener.java, the module publishes build events that extensions can monitor. It also provides the Service Provider Interface (SPI) for core extensions via AbstractMavenLifecycleParticipant.java, allowing developers to hook into the build lifecycle at specific points such as project discovery or session start.

Repository System Integration

The maven-core module wraps the Maven Resolver to fetch artifacts and manage local and remote repositories. The RepositorySystemSessionFactory.java creates the repository sessions used for resolving transitive dependencies, downloading plugins, and accessing the local repository cache.

Working with the Maven-Core API

When embedding Maven or extending its functionality, you interact directly with the maven-core module. The following examples demonstrate typical usage patterns:

// Create a Maven execution request (usually done by the CLI)
MavenExecutionRequest request = new DefaultMavenExecutionRequest();
request.setBaseDirectory(Paths.get("."));
request.setGoals(Collections.singletonList("install"));

// Obtain a Maven instance and execute the build
Maven maven = new DefaultMaven();
MavenExecutionResult result = maven.execute(request);

// Inspect the session that was created
MavenSession session = result.getSession();
System.out.println("Built " + session.getProjects().size() + " projects");

// Walk the reactor graph to see execution order
ProjectDependencyGraph graph = session.getProjectDependencyGraph();
graph.getSortedProjects().forEach(p -> System.out.println(p.getArtifactId()));

Summary

The maven-core module handles every critical aspect of the Apache Maven build process:

• Input processing – Parses command-line arguments into MavenExecutionRequest objects
• Model resolution – Transforms pom.xml files into effective MavenProject models
• Reactor construction – Builds the project dependency graph for multi-module builds
• Lifecycle execution – Resolves plugins, creates Mojos, and runs them in phase order
• Output handling – Manages artifacts, logs progress, and fires extension hooks

Frequently Asked Questions

What is the difference between maven-core and maven-cli?

The maven-cli module handles the command-line interface and user interaction, while maven-core contains the actual build engine. The CLI parses arguments and creates a MavenExecutionRequest, then delegates to the Maven interface in maven-core to perform the actual build. You can use maven-core without the CLI by embedding Maven directly in your Java applications.

How does maven-core determine the build order in multi-module projects?

The module constructs a ProjectDependencyGraph using DefaultProjectDependencyGraph.java to analyze inter-module dependencies. It performs a topological sort of the directed graph to ensure modules are built before others that declare them as dependencies. This reactor graph also detects circular dependencies and fails the build with a clear error message.

Can I extend maven-core to customize the build lifecycle?

Yes, the module provides extension points through AbstractMavenLifecycleParticipant.java. By implementing this class and registering it as an extension, you can hook into events like afterProjectsRead or afterSessionStart. Additionally, you can implement ExecutionListener to receive notifications about every MojoExecution without modifying the core code.

Where does maven-core handle artifact resolution?

While maven-resolver performs the actual artifact downloading, maven-core integrates it through RepositorySystemSessionFactory.java. This factory creates the repository system sessions that maven-core uses to resolve plugins and dependencies, manage authentication, and cache artifacts in the local repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}