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

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 file. You can find this contract at 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. 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 files. The API definition is located at 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 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.

The DefaultModelBuilder class in 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.

The corresponding implementation at 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.

The implementation at 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

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

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

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 → Implementation at 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 → Implementation at 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 → Implementation at 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 → Implementation at 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 → Implementation at 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 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.

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.

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