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

> Discover what the maven-core module handles in Apache Maven. This essential component drives the build engine and transforms your POM file into a built artifact.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: deep-dive
- Published: 2026-07-07

---

**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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/pom.xml) files and resolves parent POMs hierarchically through [`DefaultProjectBuilder.java`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/ProjectDependencyGraph.java) and [`DefaultProjectDependencyGraph.java`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/MavenExecutionRequest.java), which represents the execution plan, and [`MojoExecution.java`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/ExecutionListener.java) and [`LoggingExecutionListener.java`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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:

```java
// 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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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`](https://github.com/apache/maven/blob/main/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.