# Where to Find Maven API Definitions for Core Functionality: A Complete Guide to maven-api-core

> Find Maven API definitions for core functionality in the maven-api-core module. Locate concrete implementations within the maven-core module for your development needs.

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

---

**The core Maven API definitions are located in the `maven-api-core` module under the `org.apache.maven.api.services` package, with concrete implementations residing in the `maven-core` module.**

If you are extending Apache Maven or embedding it in your application, understanding where these **Maven API definitions for core functionality** reside is essential. The `apache/maven` repository separates stable public contracts from internal logic, allowing you to program against interfaces while the runtime handles the heavy lifting. This guide maps the exact source locations and shows you how to interact with these services programmatically.

## Maven API Architecture: Interface vs Implementation

Maven 4.0+ (and the current master branch) organizes its architecture into distinct API and implementation layers. The **API layer** lives in `api/maven-api-core` and defines service contracts in the `org.apache.maven.api.services` package. The **implementation layer** lives in `impl/maven-core` and provides concrete classes that fulfill these contracts.

All service interfaces are discovered and injected via Maven’s **DI** container (`org.apache.maven.di.Injector`). When you request a service from the container, you receive the interface type while the runtime binds it to the appropriate implementation class behind the scenes.

## Core Service Interfaces in maven-api-core

The following interfaces in the `maven-api-core` module define the primary contracts for Maven’s core functionality.

### ProjectBuilder

The `ProjectBuilder` interface defines how Maven constructs a `Project` object from a [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) file. You can find this contract at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java).

Concrete implementations reside in [`impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java). This service handles dependency resolution, inheritance assembly, and profile activation during the build process.

### SettingsBuilder

The `SettingsBuilder` interface manages the parsing and merging of Maven [`settings.xml`](https://github.com/apache/maven/blob/main/settings.xml) files. The API definition is located at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java).

The implementation at [`impl/maven-core/src/main/java/org/apache/maven/settings/building/DefaultSettingsBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/settings/building/DefaultSettingsBuilder.java) handles global and user-level settings interpolation, decryption of server passwords, and mirror configuration.

### ModelBuilder

The `ModelBuilder` interface constructs the effective project model from raw POM files before full project initialization. Find the API at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java).

The `DefaultModelBuilder` class in [`impl/maven-core/src/main/java/org/apache/maven/model/building/DefaultModelBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/model/building/DefaultModelBuilder.java) executes the complex task of parent POM resolution, plugin management injection, and profile filtering.

### ArtifactResolver

The `ArtifactResolver` interface defines the contract for resolving artifacts from remote and local repositories. View the API at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolver.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolver.java).

The corresponding implementation at [`impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultArtifactResolver.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultArtifactResolver.java) handles download logic, checksum verification, and repository chaining.

### DependencyResolver

The `DependencyResolver` interface manages transitive dependency graph resolution. The API is located at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java).

The implementation at [`impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultDependencyResolver.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultDependencyResolver.java) computes the effective dependency tree, handles conflict mediation, and manages scope filtering.

## Programmatic Usage Examples

When embedding Maven or writing extensions, you obtain these services from the DI container. Below are practical examples of using the **Maven API definitions for core functionality** in Java code.

### Building a Maven Project

```java
import org.apache.maven.api.Maven;
import org.apache.maven.api.services.ProjectBuilder;
import org.apache.maven.api.services.ProjectBuilderRequest;
import org.apache.maven.api.services.ProjectBuilderResult;
import org.apache.maven.api.model.Project;
import java.nio.file.Paths;

// Obtain the Maven runtime
Maven maven = Maven.builder().build();
ProjectBuilder builder = maven.getContainer()
                              .lookup(ProjectBuilder.class);

// Configure the build request
ProjectBuilderRequest request = ProjectBuilderRequest.builder()
        .pomFile(Paths.get("path/to/pom.xml"))
        .build();

// Execute and retrieve the project
ProjectBuilderResult result = builder.build(request);
Project project = result.getProject();

```

This uses the `ProjectBuilder` service interface defined in `maven-api-core`, while the actual execution flows through `DefaultProjectBuilder` in the `maven-core` implementation.

### Resolving an Artifact

```java
import org.apache.maven.api.services.ArtifactResolver;
import org.apache.maven.api.services.ArtifactRequest;
import org.apache.maven.api.services.ArtifactResult;
import org.apache.maven.api.Artifact;

ArtifactResolver resolver = maven.getContainer()
                                 .lookup(ArtifactResolver.class);

ArtifactRequest artReq = ArtifactRequest.builder()
        .artifact(Artifact.builder()
                     .groupId("org.apache.commons")
                     .artifactId("commons-lang3")
                     .version("3.14.0")
                     .type("jar")
                     .build())
        .build();

ArtifactResult artRes = resolver.resolve(artReq);
java.nio.file.Path artifactFile = artRes.getArtifact().getFile();

```

The `ArtifactResolver` interface specifies the `resolve()` method contract, while `DefaultArtifactResolver` in `impl/maven-core` manages the actual repository interactions.

### Loading Maven Settings

```java
import org.apache.maven.api.services.SettingsBuilder;
import org.apache.maven.api.services.SettingsBuilderRequest;
import org.apache.maven.api.settings.Settings;

SettingsBuilder settingsBuilder = maven.getContainer()
                                        .lookup(SettingsBuilder.class);

SettingsBuilderRequest sbReq = SettingsBuilderRequest.builder()
        .userSettingsFile(Paths.get(System.getProperty("user.home"), ".m2", "settings.xml"))
        .globalSettingsFile(Paths.get("/etc/maven/settings.xml"))
        .build();

Settings settings = settingsBuilder.build(sbReq).getSettings();

```

This demonstrates the `SettingsBuilder` interface usage, implemented by `DefaultSettingsBuilder` in the `maven-core` module.

## Implementation Classes in maven-core

When debugging or extending Maven, you often need to examine the actual logic. Here is the mapping between API definitions and their concrete implementations:

- **ProjectBuilder**: Interface at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java) → Implementation at [`impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java)
- **SettingsBuilder**: Interface at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilder.java) → Implementation at [`impl/maven-core/src/main/java/org/apache/maven/settings/building/DefaultSettingsBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/settings/building/DefaultSettingsBuilder.java)
- **ModelBuilder**: Interface at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java) → Implementation at [`impl/maven-core/src/main/java/org/apache/maven/model/building/DefaultModelBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/model/building/DefaultModelBuilder.java)
- **ArtifactResolver**: Interface at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolver.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolver.java) → Implementation at [`impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultArtifactResolver.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultArtifactResolver.java)
- **DependencyResolver**: Interface at [`api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java) → Implementation at [`impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultDependencyResolver.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/artifact/resolver/DefaultDependencyResolver.java)

## Summary

- The **Maven API definitions for core functionality** reside in the `maven-api-core` module under `org.apache.maven.api.services`.
- Concrete implementations live in `impl/maven-core` and follow the naming convention `Default[ServiceName]`.
- Services are accessed via Maven’s DI container (`org.apache.maven.di.Injector`) using `container.lookup(Service.class)`.
- Key interfaces include `ProjectBuilder`, `SettingsBuilder`, `ModelBuilder`, `ArtifactResolver`, and `DependencyResolver`.
- Programming against the API interfaces ensures forward compatibility while allowing Maven internals to evolve.

## Frequently Asked Questions

### What is the difference between maven-api-core and maven-core?

The `maven-api-core` module contains stable public interfaces in the `org.apache.maven.api` packages that define contracts for building projects, resolving artifacts, and reading settings. The `maven-core` module contains the actual implementation classes and runtime logic. The API module ensures backward compatibility, while the implementation module can change internally without breaking external code.

### How do I access Maven services programmatically?

You obtain services through Maven’s dependency injection container. First, build a `Maven` runtime instance using `Maven.builder().build()`, then retrieve the container and call `lookup(ServiceInterface.class)` to get the implementation. This pattern applies to all core services like `ProjectBuilder`, `ArtifactResolver`, and `SettingsBuilder`.

### Where is the ProjectBuilder interface defined?

The `ProjectBuilder` interface is defined in [`api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java) in the Apache Maven repository. This interface declares methods for building projects from POM files, while the concrete implementation resides in [`impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/ProjectBuilder.java).

### Can I use these Maven APIs in my plugin?

Yes, Maven plugins can interact with these APIs, though typically you will use the Maven Plugin API which abstracts many of these core services. For advanced use cases requiring direct access to project building or artifact resolution, you can inject the specific service interfaces (`ProjectBuilder`, `ArtifactResolver`, etc.) using Maven’s component injection mechanisms, as they are managed by the same DI container that powers the Maven runtime.