0
# Maven Core
1

2
Maven Core provides the foundational classes and interfaces for the Apache Maven build system. It serves as the core engine that orchestrates project building, dependency management, plugin execution, and lifecycle management for Java projects and beyond.
3

4
## Package Information
5

6
- **Package Name**: org.apache.maven:maven-core
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to `pom.xml` dependencies or access via Maven runtime
10
- **Version**: 3.9.11
11

12
## Core Imports
13

14
```java
15
import org.apache.maven.Maven;
16
import org.apache.maven.execution.MavenExecutionRequest;
17
import org.apache.maven.execution.MavenExecutionResult;
18
import org.apache.maven.execution.MavenSession;
19
import org.apache.maven.project.MavenProject;
20
```
21

22
Plexus Component Access:
23
```java
24
import org.codehaus.plexus.component.annotations.Component;
25
import org.apache.maven.Maven;
26
import org.apache.maven.project.ProjectBuilder;
27
import org.apache.maven.plugin.PluginManager;
28

29
@Component
30
private Maven maven;
31

32
@Component
33
private ProjectBuilder projectBuilder;
34

35
@Component 
36
private PluginManager pluginManager;
37
```
38

39
## Basic Usage
40

41
```java
42
import org.apache.maven.Maven;
43
import org.apache.maven.execution.DefaultMavenExecutionRequest;
44
import org.apache.maven.execution.MavenExecutionRequest;
45
import org.apache.maven.execution.MavenExecutionResult;
46
import org.apache.maven.project.MavenProject;
47

48
// Create and configure execution request
49
MavenExecutionRequest request = new DefaultMavenExecutionRequest();
50
request.setPom(new File("pom.xml"));
51
request.setGoals(Arrays.asList("compile", "test"));
52
request.setBaseDirectory(new File("."));
53

54
// Execute Maven build
55
Maven maven = container.lookup(Maven.class);
56
MavenExecutionResult result = maven.execute(request);
57

58
// Process results
59
if (result.hasExceptions()) {
60
    for (Throwable exception : result.getExceptions()) {
61
        System.err.println("Build error: " + exception.getMessage());
62
    }
63
} else {
64
    System.out.println("Build successful");
65
    MavenProject project = result.getProject();
66
    System.out.println("Built project: " + project.getName());
67
}
68
```
69

70
## Architecture
71

72
Maven Core follows a component-based architecture using Plexus dependency injection:
73

74
- **Execution Layer**: `Maven` interface orchestrates build execution through `MavenSession`
75
- **Project Layer**: `MavenProject` represents project model with `ProjectBuilder` for construction
76
- **Plugin Layer**: `PluginManager` and `BuildPluginManager` handle plugin lifecycle and execution
77
- **Lifecycle Layer**: `LifecycleExecutor` manages build phases and goals
78
- **Repository Layer**: `RepositorySystem` handles artifact resolution and deployment
79
- **Event System**: `ExecutionListener` and `EventSpy` provide build event notifications
80

81
## Capabilities
82

83
### Maven Execution
84

85
Core Maven build execution and session management.
86

87
```java { .api }
88
public interface Maven {
89
    MavenExecutionResult execute(MavenExecutionRequest request);
90
}
91

92
public interface MavenExecutionRequest {
93
    // Build Configuration
94
    MavenExecutionRequest setPom(File pom);
95
    MavenExecutionRequest setGoals(List<String> goals);
96
    MavenExecutionRequest setBaseDirectory(File baseDirectory);
97
    
98
    // Repository Configuration  
99
    MavenExecutionRequest setLocalRepository(ArtifactRepository localRepository);
100
    MavenExecutionRequest setRemoteRepositories(List<ArtifactRepository> repositories);
101
    
102
    // Reactor Configuration
103
    String REACTOR_FAIL_FAST = "FAIL_FAST";
104
    String REACTOR_FAIL_AT_END = "FAIL_AT_END"; 
105
    String REACTOR_FAIL_NEVER = "FAIL_NEVER";
106
    MavenExecutionRequest setReactorFailureBehavior(String failureBehavior);
107
}
108

109
public class MavenSession {
110
    public MavenProject getCurrentProject();
111
    public List<MavenProject> getProjects();
112
    public MavenExecutionRequest getRequest();
113
    public RepositorySystemSession getRepositorySession();
114
    public Map<String, Object> getUserProperties();
115
    public boolean isParallel();
116
}
117
```
118

119
[Core Execution](./core-execution.md)
120

121
### Project Management
122

123
Project model access, building, and dependency resolution.
124

125
```java { .api }
126
public class MavenProject {
127
    public Artifact getArtifact();
128
    public Model getModel();
129
    public List<Dependency> getDependencies();
130
    public List<String> getCompileSourceRoots();
131
    public List<String> getTestClasspathElements() throws DependencyResolutionRequiredException;
132
    public File getBasedir();
133
    public String getName();
134
    public String getVersion();
135
}
136

137
public interface ProjectBuilder {
138
    ProjectBuildingResult build(File projectFile, ProjectBuildingRequest request) 
139
        throws ProjectBuildingException;
140
    List<ProjectBuildingResult> build(List<File> projectFiles, boolean recursive,
141
        ProjectBuildingRequest request) throws ProjectBuildingException;
142
}
143
```
144

145
[Project Management](./project-management.md)
146

147
### Plugin System
148

149
Plugin management, execution, and caching mechanisms.
150

151
```java { .api }
152
public interface MavenPluginManager {
153
    PluginDescriptor getPluginDescriptor(Plugin plugin, List<RemoteRepository> repositories,
154
        RepositorySystemSession session) throws PluginDescriptorParsingException, InvalidPluginDescriptorException;
155
    ClassRealm setupPluginRealm(PluginDescriptor pluginDescriptor, MavenSession session,
156
        ClassLoader parent, List<String> imports, DependencyFilter filter) throws PluginManagerException;
157
    void getConfiguredMojo(Class<?> mojoInterface, MavenSession session, MojoExecution mojoExecution)
158
        throws PluginConfigurationException, PluginContainerException;
159
}
160

161
public interface BuildPluginManager {
162
    PluginDescriptor loadPlugin(Plugin plugin, List<RemoteRepository> repositories,
163
        RepositorySystemSession session) throws PluginNotFoundException, PluginResolutionException;
164
    void executeMojo(MavenSession session, MojoExecution execution) throws MojoFailureException, MojoExecutionException;
165
    ClassRealm getPluginRealm(MavenSession session, PluginDescriptor pluginDescriptor) throws PluginManagerException;
166
}
167
```
168

169
[Plugin System](./plugin-system.md)
170

171
### Lifecycle Management
172

173
Build lifecycle execution and phase management.
174

175
```java { .api }
176
public interface LifecycleExecutor {
177
    MavenExecutionPlan calculateExecutionPlan(MavenSession session, String... tasks) throws PluginNotFoundException, PluginResolutionException, LifecyclePhaseNotFoundException, LifecycleNotFoundException, InvalidPluginDescriptorException;
178
    void execute(MavenSession session);
179
    List<MavenProject> executeForkedExecutions(MojoExecution mojoExecution, MavenSession session) throws LifecycleExecutionException;
180
}
181

182
public class MavenExecutionPlan implements Iterable<MojoExecution> {
183
    public List<MojoExecution> getMojoExecutions();
184
    public Iterator<MojoExecution> iterator();
185
    public int size();
186
}
187
```
188

189
[Lifecycle Management](./lifecycle-management.md)
190

191
### Repository System
192

193
Artifact resolution, transfer, and repository operations.
194

195
```java { .api }
196
public interface RepositorySystem {
197
    ArtifactResult resolve(RepositorySystemSession session, ArtifactRequest request) throws ArtifactResolutionException;
198
    List<ArtifactResult> resolveArtifacts(RepositorySystemSession session, Collection<? extends ArtifactRequest> requests) throws ArtifactResolutionException;
199
    void publish(RepositorySystemSession session, Collection<? extends PublishRequest> requests) throws PublishException;
200
    ArtifactDescriptorResult readArtifactDescriptor(RepositorySystemSession session, ArtifactDescriptorRequest request) throws ArtifactDescriptorException;
201
    
202
    static final String DEFAULT_LOCAL_REPO_ID = "local";
203
    static final String DEFAULT_REMOTE_REPO_URL = "https://repo.maven.apache.org/maven2";
204
}
205
```
206

207
[Repository System](./repository-system.md)
208

209
### Exception Handling
210

211
Comprehensive exception handling for Maven operations.
212

213
```java { .api }
214
public class MavenExecutionException extends Exception {
215
    public MavenExecutionException(String message, Throwable cause);
216
}
217

218
public class ProjectBuildingException extends Exception {
219
    public String getProjectId();
220
    public File getPomFile();
221
    public List<ProjectBuildingResult> getResults();
222
}
223

224
public class PluginExecutionException extends PluginManagerException {
225
    public MojoExecution getMojoExecution();
226
    public MavenProject getProject();
227
}
228
```
229

230
[Exception Handling](./exception-handling.md)
231

232
### Toolchain Management
233

234
Java toolchain management for build environments.
235

236
```java { .api }
237
public interface ToolchainManager {
238
    List<Toolchain> getToolchains(MavenSession session, String type, Map<String, String> requirements);
239
    Toolchain getDefaultToolchain(MavenSession session, String type);
240
}
241

242
public interface JavaToolchain extends Toolchain {
243
    String getJavaHome();
244
    String findTool(String toolName);
245
}
246

247
public class JavaToolchainFactory implements ToolchainFactory {
248
    public Toolchain createToolchain(PersistedToolchain model) throws MisconfiguredToolchainException;
249
    public Toolchain createDefaultToolchain();
250
}
251
```
252

253
### Utility APIs
254

255
Maven runtime information and utility functions.
256

257
```java { .api }
258
public interface RuntimeInformation {
259
    String getMavenVersion();
260
    String getApplicationName();
261
    File getMavenHome();
262
}
263

264
public class RepositoryUtils {
265
    public static org.eclipse.aether.artifact.Artifact toArtifact(org.apache.maven.artifact.Artifact artifact);
266
    public static org.apache.maven.artifact.Artifact toArtifact(org.eclipse.aether.artifact.Artifact artifact);
267
    public static org.eclipse.aether.repository.RemoteRepository toRepo(ArtifactRepository repository);
268
    public static List<org.eclipse.aether.repository.RemoteRepository> toRepos(List<ArtifactRepository> repositories);
269
}
270

271
public interface ArtifactFilterManager {
272
    ArtifactFilter getArtifactFilter();
273
    ArtifactFilter getCoreArtifactFilter();
274
}
275
```
276

277
## Types
278

279
### Core Execution Types
280

281
```java { .api }
282
public interface MavenExecutionResult {
283
    MavenProject getProject();
284
    List<MavenProject> getTopologicallySortedProjects();
285
    DependencyResolutionResult getDependencyResolutionResult();
286
    List<Throwable> getExceptions();
287
    Map<MavenProject, BuildSummary> getBuildSummary(MavenProject project);
288
    boolean hasExceptions();
289
}
290

291
public class MojoExecution {
292
    public String getExecutionId();
293
    public Plugin getPlugin();
294
    public String getGoal();
295
    public String getLifecyclePhase();
296
    public MojoDescriptor getMojoDescriptor();
297
    public PlexusConfiguration getConfiguration();
298
}
299

300
public interface ExecutionListener {
301
    void projectDiscoveryStarted(ExecutionEvent event);
302
    void sessionStarted(ExecutionEvent event);
303
    void sessionEnded(ExecutionEvent event);
304
    void projectSkipped(ExecutionEvent event);
305
    void projectStarted(ExecutionEvent event);
306
    void projectSucceeded(ExecutionEvent event);
307
    void projectFailed(ExecutionEvent event);
308
    void mojoSkipped(ExecutionEvent event);
309
    void mojoStarted(ExecutionEvent event);
310
    void mojoSucceeded(ExecutionEvent event);
311
    void mojoFailed(ExecutionEvent event);
312
    void forkStarted(ExecutionEvent event);
313
    void forkSucceeded(ExecutionEvent event);
314
    void forkFailed(ExecutionEvent event);
315
    void forkedProjectStarted(ExecutionEvent event);
316
    void forkedProjectSucceeded(ExecutionEvent event);
317
    void forkedProjectFailed(ExecutionEvent event);
318
}
319
```
320

321
### Repository Types
322

323
```java { .api }
324
public interface ArtifactRepository {
325
    String getId();
326
    String getUrl();
327
    ArtifactRepositoryLayout getLayout();
328
    ArtifactRepositoryPolicy getSnapshots();
329
    ArtifactRepositoryPolicy getReleases();
330
    boolean isUniqueVersion();
331
    boolean isBlacklisted();
332
}
333

334
public interface ArtifactTransferListener {
335
    void transferInitiated(ArtifactTransferEvent event);
336
    void transferStarted(ArtifactTransferEvent event);
337
    void transferProgress(ArtifactTransferEvent event);
338
    void transferCompleted(ArtifactTransferEvent event);
339
}
340

341
public class ArtifactTransferEvent {
342
    public static final int TRANSFER_INITIATED = 1;
343
    public static final int TRANSFER_STARTED = 2; 
344
    public static final int TRANSFER_COMPLETED = 3;
345
    public static final int TRANSFER_ERROR = 4;
346
    
347
    public Artifact getArtifact();
348
    public Exception getException();
349
    public File getLocalFile();
350
    public ArtifactRepository getRepository();
351
}
352
```
353

354
### Toolchain Types
355

356
```java { .api }
357
public interface Toolchain {
358
    String getType();
359
    String findTool(String toolName);
360
}
361

362
public interface ToolchainManager {
363
    Toolchain getToolchainFromBuildContext(String type, MavenSession session);
364
    List<Toolchain> getToolchains(MavenSession session, String type, Map<String, String> requirements);
365
}
366

367
public interface JavaToolchain extends Toolchain {
368
    // Java-specific toolchain interface that extends base Toolchain
369
}
370
```