0
# Project Building
1

2
Legacy project building system for constructing Maven projects from POM files with Maven2 compatibility patterns.
3

4
## Capabilities
5

6
### MavenProjectBuilder
7

8
Main interface for building Maven projects from POM files and artifacts.
9

10
```java { .api }
11
/**
12
 * Interface for building Maven projects from POM files and artifacts
13
 * @deprecated Use ProjectBuilder instead
14
 */
15
@Deprecated
16
public interface MavenProjectBuilder {
17
    /**
18
     * Builds a Maven project from a POM file
19
     * @param pom POM file to build from
20
     * @param configuration builder configuration
21
     * @return constructed MavenProject
22
     * @throws ProjectBuildingException if building fails
23
     */
24
    MavenProject build(File pom, ProjectBuilderConfiguration configuration) 
25
                      throws ProjectBuildingException;
26
    
27
    /**
28
     * Builds a Maven project from an artifact in repositories
29
     * @param artifact artifact to build project for
30
     * @param remoteRepositories remote repositories to search
31
     * @param localRepository local repository
32
     * @return constructed MavenProject
33
     * @throws ProjectBuildingException if building fails
34
     */
35
    MavenProject buildFromRepository(Artifact artifact, List<ArtifactRepository> remoteRepositories, 
36
                                   ArtifactRepository localRepository) 
37
                                   throws ProjectBuildingException;
38
    
39
    /**
40
     * Builds a standalone super project
41
     * @param configuration builder configuration
42
     * @return constructed super MavenProject
43
     * @throws ProjectBuildingException if building fails
44
     */
45
    MavenProject buildStandaloneSuperProject(ProjectBuilderConfiguration configuration) 
46
                                           throws ProjectBuildingException;
47
    
48
    /**
49
     * Builds project with dependencies resolved (deprecated)
50
     * @param pom POM file to build from
51
     * @param localRepository local repository
52
     * @param globalProfileManager profile manager for activation
53
     * @return constructed MavenProject with dependencies
54
     * @throws ProjectBuildingException if building fails
55
     * @deprecated Use build(File, ProjectBuilderConfiguration) instead
56
     */
57
    @Deprecated
58
    MavenProject buildWithDependencies(File pom, ArtifactRepository localRepository, 
59
                                     ProfileManager globalProfileManager) 
60
                                     throws ProjectBuildingException;
61
}
62
```
63

64
### DefaultMavenProjectBuilder
65

66
Default implementation of MavenProjectBuilder.
67

68
```java { .api }
69
/**
70
 * Default implementation of MavenProjectBuilder
71
 */
72
public class DefaultMavenProjectBuilder implements MavenProjectBuilder {
73
    /**
74
     * Builds a Maven project from a POM file
75
     */
76
    public MavenProject build(File pom, ProjectBuilderConfiguration configuration) 
77
                             throws ProjectBuildingException;
78
    
79
    /**
80
     * Builds a Maven project from an artifact in repositories
81
     */
82
    public MavenProject buildFromRepository(Artifact artifact, List<ArtifactRepository> remoteRepositories, 
83
                                          ArtifactRepository localRepository) 
84
                                          throws ProjectBuildingException;
85
    
86
    /**
87
     * Builds a standalone super project
88
     */
89
    public MavenProject buildStandaloneSuperProject(ProjectBuilderConfiguration configuration) 
90
                                                  throws ProjectBuildingException;
91
}
92
```
93

94
### ProjectBuilderConfiguration
95

96
Interface for configuring project building behavior.
97

98
```java { .api }
99
/**
100
 * Configuration interface for project building behavior
101
 */
102
public interface ProjectBuilderConfiguration {
103
    /**
104
     * Gets the local repository
105
     * @return local ArtifactRepository
106
     */
107
    ArtifactRepository getLocalRepository();
108
    
109
    /**
110
     * Sets the local repository
111
     * @param localRepository local repository to use
112
     */
113
    void setLocalRepository(ArtifactRepository localRepository);
114
    
115
    /**
116
     * Gets remote repositories
117
     * @return List of remote ArtifactRepository objects
118
     */
119
    List<ArtifactRepository> getRemoteRepositories();
120
    
121
    /**
122
     * Sets remote repositories
123
     * @param remoteRepositories list of remote repositories
124
     */
125
    void setRemoteRepositories(List<ArtifactRepository> remoteRepositories);
126
    
127
    /**
128
     * Gets the profile manager
129
     * @return ProfileManager for profile activation
130
     */
131
    ProfileManager getGlobalProfileManager();
132
    
133
    /**
134
     * Sets the profile manager
135
     * @param globalProfileManager profile manager to use
136
     */
137
    void setGlobalProfileManager(ProfileManager globalProfileManager);
138
    
139
    /**
140
     * Gets build start time
141
     * @return Date when build started
142
     */
143
    Date getBuildStartTime();
144
    
145
    /**
146
     * Sets build start time
147
     * @param buildStartTime build start timestamp
148
     */
149
    void setBuildStartTime(Date buildStartTime);
150
    
151
    /**
152
     * Gets user properties
153
     * @return Properties from user input
154
     */
155
    Properties getUserProperties();
156
    
157
    /**
158
     * Sets user properties
159
     * @param userProperties user-defined properties
160
     */
161
    void setUserProperties(Properties userProperties);
162
    
163
    /**
164
     * Gets execution properties
165
     * @return Properties for execution context
166
     */
167
    Properties getExecutionProperties();
168
    
169
    /**
170
     * Sets execution properties
171
     * @param executionProperties execution context properties
172
     */
173
    void setExecutionProperties(Properties executionProperties);
174
}
175
```
176

177
### DefaultProjectBuilderConfiguration
178

179
Default implementation of ProjectBuilderConfiguration.
180

181
```java { .api }
182
/**
183
 * Default implementation of ProjectBuilderConfiguration
184
 */
185
public class DefaultProjectBuilderConfiguration implements ProjectBuilderConfiguration {
186
    /**
187
     * Creates default configuration
188
     */
189
    public DefaultProjectBuilderConfiguration();
190
    
191
    /**
192
     * Gets the local repository
193
     */
194
    public ArtifactRepository getLocalRepository();
195
    
196
    /**
197
     * Sets the local repository
198
     */
199
    public void setLocalRepository(ArtifactRepository localRepository);
200
    
201
    /**
202
     * Gets remote repositories
203
     */
204
    public List<ArtifactRepository> getRemoteRepositories();
205
    
206
    /**
207
     * Sets remote repositories
208
     */
209
    public void setRemoteRepositories(List<ArtifactRepository> remoteRepositories);
210
    
211
    /**
212
     * Gets the profile manager
213
     */
214
    public ProfileManager getGlobalProfileManager();
215
    
216
    /**
217
     * Sets the profile manager
218
     */
219
    public void setGlobalProfileManager(ProfileManager globalProfileManager);
220
    
221
    /**
222
     * Gets build start time
223
     */
224
    public Date getBuildStartTime();
225
    
226
    /**
227
     * Sets build start time
228
     */
229
    public void setBuildStartTime(Date buildStartTime);
230
    
231
    /**
232
     * Gets user properties
233
     */
234
    public Properties getUserProperties();
235
    
236
    /**
237
     * Sets user properties
238
     */
239
    public void setUserProperties(Properties userProperties);
240
    
241
    /**
242
     * Gets execution properties
243
     */
244
    public Properties getExecutionProperties();
245
    
246
    /**
247
     * Sets execution properties
248
     */
249
    public void setExecutionProperties(Properties executionProperties);
250
}
251
```
252

253
## Model Processing
254

255
### ModelInterpolator
256

257
Interface for interpolating variables in Maven models.
258

259
```java { .api }
260
/**
261
 * Interface for interpolating variables in Maven models
262
 * @deprecated Use newer model building APIs
263
 */
264
@Deprecated
265
public interface ModelInterpolator {
266
    /**
267
     * Default timestamp format for build timestamps
268
     */
269
    String DEFAULT_BUILD_TIMESTAMP_FORMAT = "yyyyMMdd-HHmm";
270
    
271
    /**
272
     * Interpolates variables in a Maven model
273
     * @param model model to interpolate
274
     * @param projectDir project directory for relative path resolution
275
     * @param config project builder configuration
276
     * @param debugEnabled whether debug output is enabled
277
     * @return interpolated model
278
     * @throws ModelInterpolationException if interpolation fails
279
     */
280
    Model interpolate(Model model, File projectDir, ProjectBuilderConfiguration config, boolean debugEnabled) 
281
                     throws ModelInterpolationException;
282
    
283
    /**
284
     * Interpolates variables in a string
285
     * @param src source string to interpolate
286
     * @param model model providing variable context
287
     * @param projectDir project directory
288
     * @param config project builder configuration
289
     * @param debugEnabled whether debug output is enabled
290
     * @return interpolated string
291
     * @throws ModelInterpolationException if interpolation fails
292
     */
293
    String interpolate(String src, Model model, File projectDir, ProjectBuilderConfiguration config, 
294
                      boolean debugEnabled) throws ModelInterpolationException;
295
}
296
```
297

298
### ModelValidator
299

300
Interface for validating Maven project models.
301

302
```java { .api }
303
/**
304
 * Interface for validating Maven project models
305
 * @deprecated Use newer model validation APIs
306
 */
307
@Deprecated
308
public interface ModelValidator {
309
    /**
310
     * Role constant for Plexus component lookup
311
     */
312
    String ROLE = ModelValidator.class.getName();
313
    
314
    /**
315
     * Validates a Maven model
316
     * @param model model to validate
317
     * @return validation result with any errors or warnings
318
     */
319
    ModelValidationResult validate(Model model);
320
}
321
```
322

323
### ModelValidationResult
324

325
Container for model validation results.
326

327
```java { .api }
328
/**
329
 * Container for model validation results
330
 */
331
public class ModelValidationResult {
332
    /**
333
     * Creates empty validation result
334
     */
335
    public ModelValidationResult();
336
    
337
    /**
338
     * Gets number of validation messages
339
     * @return count of validation messages
340
     */
341
    public int getMessageCount();
342
    
343
    /**
344
     * Gets validation messages
345
     * @return List of validation message strings
346
     */
347
    public List<String> getMessages();
348
    
349
    /**
350
     * Adds a validation message
351
     * @param message validation message to add
352
     */
353
    public void addMessage(String message);
354
    
355
    /**
356
     * Checks if validation has any messages
357
     * @return true if there are validation messages
358
     */
359
    public boolean hasMessages();
360
}
361
```
362

363
## Usage Examples
364

365
### Basic Project Building
366

367
```java
368
import org.apache.maven.project.MavenProjectBuilder;
369
import org.apache.maven.project.DefaultMavenProjectBuilder;
370
import org.apache.maven.project.ProjectBuilderConfiguration;
371
import org.apache.maven.project.DefaultProjectBuilderConfiguration;
372
import org.apache.maven.project.MavenProject;
373

374
// Create project builder
375
MavenProjectBuilder builder = new DefaultMavenProjectBuilder();
376

377
// Configure builder
378
ProjectBuilderConfiguration config = new DefaultProjectBuilderConfiguration();
379
config.setLocalRepository(localRepository);
380
config.setRemoteRepositories(remoteRepositories);
381
config.setGlobalProfileManager(profileManager);
382
config.setBuildStartTime(new Date());
383

384
try {
385
    // Build project from POM
386
    File pomFile = new File("pom.xml");
387
    MavenProject project = builder.build(pomFile, config);
388
    
389
    System.out.println("Built project: " + project.getArtifactId());
390
    System.out.println("Version: " + project.getVersion());
391
    System.out.println("Dependencies: " + project.getDependencies().size());
392
    
393
} catch (ProjectBuildingException e) {
394
    System.err.println("Project building failed: " + e.getMessage());
395
}
396
```
397

398
### Building from Repository Artifact
399

400
```java
401
// Build project from artifact in repository
402
Artifact projectArtifact = // ... create or obtain artifact
403
List<ArtifactRepository> remoteRepos = // ... configure remote repositories
404

405
try {
406
    MavenProject project = builder.buildFromRepository(
407
        projectArtifact, 
408
        remoteRepos, 
409
        localRepository
410
    );
411
    
412
    System.out.println("Built project from artifact: " + project.getArtifactId());
413
    
414
} catch (ProjectBuildingException e) {
415
    System.err.println("Failed to build from repository: " + e.getMessage());
416
}
417
```
418

419
### Standalone Super Project
420

421
```java
422
// Build standalone super project
423
try {
424
    MavenProject superProject = builder.buildStandaloneSuperProject(config);
425
    System.out.println("Created super project: " + superProject.getArtifactId());
426
    
427
} catch (ProjectBuildingException e) {
428
    System.err.println("Super project creation failed: " + e.getMessage());
429
}
430
```
431

432
### Model Interpolation
433

434
```java
435
import org.apache.maven.project.interpolation.ModelInterpolator;
436
import org.apache.maven.project.interpolation.ModelInterpolationException;
437
import org.apache.maven.model.Model;
438

439
// Interpolate model variables
440
ModelInterpolator interpolator = // ... get interpolator instance
441
Model model = // ... load model
442
File projectDir = new File(".");
443

444
try {
445
    Model interpolatedModel = interpolator.interpolate(
446
        model, 
447
        projectDir, 
448
        config, 
449
        false // debug disabled
450
    );
451
    
452
    System.out.println("Model interpolated successfully");
453
    
454
    // Interpolate individual string
455
    String interpolatedString = interpolator.interpolate(
456
        "${project.version}", 
457
        model, 
458
        projectDir, 
459
        config, 
460
        false
461
    );
462
    System.out.println("Interpolated version: " + interpolatedString);
463
    
464
} catch (ModelInterpolationException e) {
465
    System.err.println("Interpolation failed: " + e.getMessage());
466
}
467
```
468

469
### Model Validation
470

471
```java
472
import org.apache.maven.project.validation.ModelValidator;
473
import org.apache.maven.project.validation.ModelValidationResult;
474

475
// Validate model
476
ModelValidator validator = // ... get validator instance
477
Model model = // ... load model
478

479
ModelValidationResult result = validator.validate(model);
480

481
if (result.hasMessages()) {
482
    System.out.println("Validation issues found:");
483
    for (String message : result.getMessages()) {
484
        System.out.println("  - " + message);
485
    }
486
} else {
487
    System.out.println("Model validation passed");
488
}
489
```
490

491
### Complete Project Building Workflow
492

493
```java
494
public MavenProject buildProjectComplete(File pomFile) {
495
    try {
496
        // Create and configure builder
497
        MavenProjectBuilder builder = new DefaultMavenProjectBuilder();
498
        ProjectBuilderConfiguration config = new DefaultProjectBuilderConfiguration();
499
        
500
        // Set up repositories
501
        config.setLocalRepository(createLocalRepository());
502
        config.setRemoteRepositories(createRemoteRepositories());
503
        
504
        // Set up profile management
505
        ProfileManager profileManager = new DefaultProfileManager();
506
        config.setGlobalProfileManager(profileManager);
507
        
508
        // Set build properties
509
        config.setBuildStartTime(new Date());
510
        config.setUserProperties(System.getProperties());
511
        
512
        // Build the project
513
        MavenProject project = builder.build(pomFile, config);
514
        
515
        // Validate the built project
516
        validateProject(project);
517
        
518
        return project;
519
        
520
    } catch (ProjectBuildingException e) {
521
        throw new RuntimeException("Failed to build project", e);
522
    }
523
}
524

525
private void validateProject(MavenProject project) {
526
    ModelValidator validator = // ... get validator
527
    ModelValidationResult result = validator.validate(project.getModel());
528
    
529
    if (result.hasMessages()) {
530
        System.out.println("Project validation warnings:");
531
        result.getMessages().forEach(msg -> System.out.println("  " + msg));
532
    }
533
}
534
```
535

536
## Exception Handling
537

538
### ProjectBuildingException
539

540
```java { .api }
541
/**
542
 * Exception thrown when project building fails
543
 */
544
public class ProjectBuildingException extends Exception {
545
    /**
546
     * Creates exception with message
547
     * @param message error message
548
     */
549
    public ProjectBuildingException(String message);
550
    
551
    /**
552
     * Creates exception with message and cause
553
     * @param message error message
554
     * @param cause underlying cause
555
     */
556
    public ProjectBuildingException(String message, Throwable cause);
557
}
558
```
559

560
### ModelInterpolationException
561

562
```java { .api }
563
/**
564
 * Exception thrown when model interpolation fails
565
 */
566
public class ModelInterpolationException extends Exception {
567
    /**
568
     * Creates exception with message
569
     * @param message error message
570
     */
571
    public ModelInterpolationException(String message);
572
    
573
    /**
574
     * Creates exception with message and cause
575
     * @param message error message
576
     * @param cause underlying cause
577
     */
578
    public ModelInterpolationException(String message, Throwable cause);
579
}
580
```
581

582
## Migration Notes
583

584
The project building system in maven-compat is deprecated. Modern Maven 3.x applications should use:
585

586
- `org.apache.maven.project.ProjectBuilder` instead of `MavenProjectBuilder`
587
- `org.apache.maven.project.ProjectBuildingRequest` instead of `ProjectBuilderConfiguration`
588
- `org.apache.maven.model.building.ModelBuilder` for model processing
589
- Standard Maven 3.x dependency injection instead of Plexus component lookup