0
# Data Model and Tree Structures
1

2
Complete data model representing Maven POM files, dependencies, plugins, and all Maven concepts.
3

4
## Capabilities
5

6
### Core POM Representation
7

8
The `Pom` class represents the essential structure of a Maven POM file.
9

10
```java { .api }
11
/**
12
 * Represents a Maven POM with all its metadata and dependencies
13
 * The cacheable representation of POMs
14
 */
15
@Value
16
@With
17
@Builder
18
public class Pom implements Serializable {
19
    /**
20
     * Get project group ID
21
     */
22
    public @Nullable String getGroupId();
23
    
24
    /**
25
     * Get project artifact ID
26
     */
27
    public String getArtifactId();
28
    
29
    /**
30
     * Get project version
31
     */
32
    public @Nullable String getVersion();
33
    
34
    /**
35
     * Get project properties
36
     */
37
    public Map<String, String> getProperties();
38
    
39
    /**
40
     * Get project dependencies
41
     */
42
    public List<Dependency> getDependencies();
43
    
44
    /**
45
     * Get managed dependencies
46
     */
47
    public List<ManagedDependency> getDependencyManagement();
48
    
49
    /**
50
     * Get build plugins
51
     */
52
    public List<Plugin> getPlugins();
53
    
54
    /**
55
     * Get parent POM reference
56
     */
57
    public @Nullable Parent getParent();
58
}
59
```
60

61
### Resolved POM
62

63
The `ResolvedPom` class provides a fully resolved view of a POM with all dependencies resolved.
64

65
```java { .api }
66
/**
67
 * Fully resolved POM with dependency resolution completed
68
 * Internal data structure - use MavenResolutionResult for dependency access
69
 */
70
public class ResolvedPom {
71
    /**
72
     * Get the underlying POM
73
     */
74
    public Pom getPom();
75
    
76
    /**
77
     * Get effective properties after resolution
78
     */
79
    public Map<String, String> getProperties();
80
    
81
    /**
82
     * Get Maven repositories used for resolution
83
     */
84
    public List<MavenRepository> getRepositories();
85
}
86
```
87

88
### Maven Resolution Result
89

90
Marker containing resolved Maven project information attached to XML documents.
91

92
```java { .api }
93
/**
94
 * Contains resolved Maven project information attached to XML documents
95
 * Primary interface for accessing Maven dependency information
96
 */
97
public class MavenResolutionResult {
98
    /**
99
     * Get the resolved POM
100
     */
101
    public ResolvedPom getPom();
102
    
103
    /**
104
     * Get resolved dependencies grouped by scope
105
     */
106
    public Map<Scope, List<ResolvedDependency>> getDependencies();
107
    
108
    /**
109
     * Find dependencies matching group and artifact ID
110
     */
111
    public List<ResolvedDependency> findDependencies(String groupId, String artifactId);
112
    
113
    /**
114
     * Get Maven modules if this is a multi-module project
115
     */
116
    public Map<Path, ResolvedPom> getModules();
117
    
118
    /**
119
     * Find module by path
120
     */
121
    public @Nullable ResolvedPom findModule(Path path);
122
}
123
```
124

125
**Usage Examples:**
126

127
```java
128
// Access resolution result from parsed document
129
Xml.Document pomDocument = (Xml.Document) parsedFiles.get(0);
130
MavenResolutionResult result = pomDocument.getMarkers()
131
    .findFirst(MavenResolutionResult.class)
132
    .orElse(null);
133

134
if (result != null) {
135
    ResolvedPom resolvedPom = result.getPom();
136
    Pom pom = resolvedPom.getPom();
137
    
138
    // Access project information
139
    String groupId = pom.getGroupId();
140
    String artifactId = pom.getArtifactId();
141
    String version = pom.getVersion();
142
    System.out.println("Project: " + groupId + ":" + artifactId + ":" + version);
143
    
144
    // Access dependencies by scope
145
    Map<Scope, List<ResolvedDependency>> dependenciesByScope = result.getDependencies();
146
    for (Map.Entry<Scope, List<ResolvedDependency>> entry : dependenciesByScope.entrySet()) {
147
        Scope scope = entry.getKey();
148
        List<ResolvedDependency> dependencies = entry.getValue();
149
        System.out.println("Dependencies in " + scope + " scope:");
150
        for (ResolvedDependency dep : dependencies) {
151
            System.out.println("  " + dep.getGroupId() + ":" + dep.getArtifactId() + ":" + dep.getVersion());
152
        }
153
    }
154
}
155
```
156

157
### Maven Coordinates
158

159
Classes representing different levels of Maven coordinates.
160

161
#### GroupArtifact
162

163
```java { .api }
164
/**
165
 * Represents Maven groupId:artifactId coordinate
166
 */
167
@Value
168
public class GroupArtifact implements Serializable {
169
    String groupId;
170
    String artifactId;
171
    
172
    /**
173
     * Create from string in format "groupId:artifactId"
174
     */
175
    public static GroupArtifact fromCoordinates(String coordinates);
176
}
177
```
178

179
#### GroupArtifactVersion
180

181
```java { .api }
182
/**
183
 * Represents Maven groupId:artifactId:version coordinate
184
 */
185
@Value  
186
public class GroupArtifactVersion implements Serializable {
187
    String groupId;
188
    String artifactId;
189
    @Nullable String version;
190
    
191
    /**
192
     * Create from string in format "groupId:artifactId:version"
193
     */
194
    public static GroupArtifactVersion fromCoordinates(String coordinates);
195
    
196
    /**
197
     * Convert to GroupArtifact
198
     */
199
    public GroupArtifact asGroupArtifact();
200
}
201
```
202

203
#### ResolvedGroupArtifactVersion
204

205
```java { .api }
206
/**
207
 * Resolved GAV with effective version determined
208
 */
209
@Value
210
public class ResolvedGroupArtifactVersion implements Serializable {
211
    String groupId;
212
    String artifactId;
213
    String version;          // Resolved effective version
214
    @Nullable String datedSnapshotVersion;  // For snapshot versions
215
    
216
    /**
217
     * Get the repository where this was resolved from
218
     */
219
    public @Nullable MavenRepository getRepository();
220
}
221
```
222

223
### Dependency Model
224

225
#### Dependency
226

227
```java { .api }
228
/**
229
 * Represents a Maven dependency
230
 */
231
@Value
232
@With
233
@Builder
234
public class Dependency implements Serializable, Attributed {
235
    String groupId;
236
    String artifactId;
237
    @Nullable String version;
238
    @Nullable String classifier;
239
    @Nullable String type;           // Default: "jar"
240
    @Nullable Scope scope;           // Default: Compile
241
    @Nullable Boolean optional;      // Default: false
242
    List<GroupArtifact> exclusions;  // Dependencies to exclude
243
    
244
    /**
245
     * Convert to coordinate representation
246
     */
247
    public GroupArtifactVersion getGav();
248
    
249
    /**
250
     * Check if this dependency matches given coordinates
251
     */
252
    public boolean matches(String groupId, String artifactId);
253
}
254
```
255

256
#### ResolvedDependency
257

258
```java { .api }
259
/**
260
 * Fully resolved dependency with transitive dependencies
261
 */
262
@Value
263
public class ResolvedDependency implements Serializable {
264
    ResolvedGroupArtifactVersion gav;
265
    @Nullable String classifier;
266
    @Nullable String type;
267
    Scope scope;
268
    @Nullable Boolean optional;
269
    List<ResolvedDependency> dependencies;  // Transitive dependencies
270
    
271
    /**
272
     * Get direct coordinate access
273
     */
274
    public String getGroupId();
275
    public String getArtifactId();
276
    public String getVersion();
277
    
278
    /**
279
     * Find transitive dependency
280
     */
281
    public @Nullable ResolvedDependency findDependency(String groupId, String artifactId);
282
    
283
    /**
284
     * Get all dependencies recursively (depth-first)
285
     */
286
    public List<ResolvedDependency> getDependenciesRecursively();
287
}
288
```
289

290
**Usage Examples:**
291

292
```java
293
// Create a new dependency
294
Dependency junitDependency = Dependency.builder()
295
    .groupId("org.junit.jupiter")
296
    .artifactId("junit-jupiter")
297
    .version("5.8.2")
298
    .scope(Scope.Test)
299
    .build();
300

301
// Work with resolved dependencies
302
List<ResolvedDependency> springCoreDeps = result.findDependencies("org.springframework", "spring-core");
303
ResolvedDependency resolvedDep = springCoreDeps.isEmpty() ? null : springCoreDeps.get(0);
304
if (resolvedDep != null) {
305
    System.out.println("Spring Core version: " + resolvedDep.getVersion());
306
    
307
    // Check transitive dependencies
308
    List<ResolvedDependency> transitives = resolvedDep.getDependenciesRecursively();
309
    for (ResolvedDependency transitive : transitives) {
310
        System.out.println("  Transitive: " + transitive.getGroupId() + ":" + transitive.getArtifactId());
311
    }
312
}
313
```
314

315
### Managed Dependencies
316

317
#### ManagedDependency Interface
318

319
```java { .api }
320
/**
321
 * Interface for managed dependencies in dependencyManagement section
322
 */
323
public interface ManagedDependency {
324
    String getGroupId();
325
    String getArtifactId(); 
326
    @Nullable String getVersion();
327
    @Nullable String getClassifier();
328
    @Nullable String getType();
329
    @Nullable Scope getScope();
330
    List<GroupArtifact> getExclusions();
331
}
332
```
333

334
#### ResolvedManagedDependency
335

336
```java { .api }
337
/**
338
 * Resolved managed dependency implementation
339
 */
340
@Value
341
public class ResolvedManagedDependency implements ManagedDependency {
342
    ResolvedGroupArtifactVersion gav;
343
    @Nullable String classifier;
344
    @Nullable String type;
345
    @Nullable Scope scope;
346
    List<GroupArtifact> exclusions;
347
    
348
    // Implements all ManagedDependency methods
349
}
350
```
351

352
### Dependency Scopes
353

354
```java { .api }
355
/**
356
 * Maven dependency scopes with precedence and behavior rules
357
 */
358
public enum Scope {
359
    Compile,    // Default scope, available in all classpaths
360
    Test,       // Only available for test compilation and execution  
361
    Runtime,    // Not required for compilation but needed for execution
362
    Provided,   // Expected to be provided by runtime environment
363
    System,     // Similar to provided but must be explicitly provided
364
    Import;     // Only supported on dependency of type 'pom' in dependencyManagement
365
    
366
    /**
367
     * Check if this scope is wider than another scope
368
     */
369
    public boolean isInClasspathOf(Scope other);
370
    
371
    /**
372
     * Convert to Gradle equivalent scope
373
     */
374
    public String toGradleConfiguration();
375
}
376
```
377

378
### Version Handling
379

380
```java { .api }
381
/**
382
 * Maven version representation and comparison
383
 */
384
public class Version implements Comparable<Version> {
385
    /**
386
     * Parse version string
387
     */
388
    public static Version valueOf(String version);
389
    
390
    /**
391
     * Check if this is a snapshot version
392
     */
393
    public boolean isSnapshot();
394
    
395
    /**
396
     * Get version components
397
     */
398
    public List<String> getComponents();
399
    
400
    /**
401
     * Compare versions according to Maven rules
402
     */
403
    @Override
404
    public int compareTo(Version other);
405
}
406
```
407

408
### Repository Model
409

410
```java { .api }
411
/**
412
 * Represents Maven repository configuration
413
 */
414
@Value
415
@Builder
416
public class MavenRepository implements Serializable {
417
    String id;
418
    String uri; 
419
    boolean releases;        // Allow release artifacts
420
    boolean snapshots;       // Allow snapshot artifacts
421
    @Nullable String username;
422
    @Nullable String password;
423
    
424
    /**
425
     * Check if this repository allows release artifacts
426
     */
427
    public boolean acceptsReleases();
428
    
429
    /**
430
     * Check if this repository allows snapshot artifacts  
431
     */
432
    public boolean acceptsSnapshots();
433
}
434
```
435

436
### Plugin Model
437

438
```java { .api }
439
/**
440
 * Represents Maven plugin configuration
441
 */
442
@Value
443
@With
444
@Builder
445
public class Plugin implements Serializable {
446
    String groupId;          // Default: "org.apache.maven.plugins"
447
    String artifactId;
448
    @Nullable String version;
449
    @Nullable Object configuration;    // Plugin-specific configuration
450
    List<PluginExecution> executions;
451
    List<Dependency> dependencies;     // Plugin dependencies
452
    
453
    /**
454
     * Get full plugin coordinate
455
     */
456
    public GroupArtifactVersion getGav();
457
    
458
    /**
459
     * Check if this plugin matches coordinates
460
     */
461
    public boolean matches(String groupId, String artifactId);
462
}
463
```
464

465
### Project Metadata
466

467
#### Parent POM Reference
468

469
```java { .api }
470
/**
471
 * Represents parent POM reference
472
 */
473
@Value
474
public class Parent {
475
    GroupArtifactVersion gav;
476
    @Nullable String relativePath;   // Default: "../pom.xml"
477
    
478
    public String getGroupId();
479
    public String getArtifactId();
480
    public String getVersion();
481
}
482
```
483

484
#### License Information
485

486
```java { .api }
487
/**
488
 * Represents project license information
489
 */
490
@Value
491
public class License {
492
    String name;
493
    @Nullable String url;
494
    @Nullable String distribution;
495
    @Nullable String comments;
496
}
497
```
498

499
#### Prerequisites
500

501
```java { .api }
502
/**
503
 * Represents Maven prerequisites (like minimum Maven version)
504
 */
505
@Value
506
public class Prerequisites {
507
    @Nullable String maven;      // Minimum Maven version required
508
}
509
```
510

511
### Profile Support
512

513
```java { .api }
514
/**
515
 * Represents Maven build profiles
516
 */
517
@Value
518
public class Profile {
519
    String id;
520
    @Nullable ProfileActivation activation;
521
    List<Dependency> dependencies;
522
    List<ManagedDependency> dependencyManagement;
523
    List<Plugin> plugins;
524
    Map<String, String> properties;
525
    List<MavenRepository> repositories;
526
}
527

528
/**
529
 * Profile activation conditions
530
 */
531
@Value  
532
public class ProfileActivation {
533
    boolean activeByDefault;
534
    @Nullable String jdk;        // JDK version requirement
535
    @Nullable String os;         // OS requirement
536
    @Nullable String property;   // System property requirement
537
    @Nullable String file;       // File existence requirement
538
}
539
```
540

541
### Attribute System
542

543
```java { .api }
544
/**
545
 * Base interface for Maven element attributes
546
 */
547
public interface Attribute extends Serializable {
548
    // Marker interface for attributes
549
}
550

551
/**
552
 * Interface for elements that can have attributes
553
 */
554
public interface Attributed {
555
    /**
556
     * Get all attributes attached to this element
557
     */
558
    List<Attribute> getAttributes();
559
    
560
    /**
561
     * Add an attribute to this element
562
     */
563
    <T extends Attributed> T withAttributes(List<Attribute> attributes);
564
}
565
```
566

567
**Usage Examples:**
568

569
```java
570
// Working with the complete data model
571
ResolvedPom resolvedPom = result.getPom();
572
Pom pom = resolvedPom.getPom();
573

574
// Access project metadata
575
String projectGroupId = pom.getGroupId();
576
String projectArtifactId = pom.getArtifactId(); 
577
String projectVersion = pom.getVersion();
578
Parent parent = pom.getParent();
579
Map<String, String> properties = resolvedPom.getProperties();
580

581
// Work with dependencies by scope
582
Map<Scope, List<ResolvedDependency>> dependenciesByScope = result.getDependencies();
583
List<ResolvedDependency> testDeps = dependenciesByScope.get(Scope.Test);
584
if (testDeps != null) {
585
    for (ResolvedDependency dep : testDeps) {
586
        System.out.println("Test dependency: " + dep.getGroupId() + ":" + dep.getArtifactId() + ":" + dep.getVersion());
587
    }
588
}
589

590
// Access repositories
591
List<MavenRepository> repos = resolvedPom.getRepositories();
592
for (MavenRepository repo : repos) {
593
    if (repo.acceptsSnapshots()) {
594
        System.out.println("Snapshot repository: " + repo.getUri());
595
    }
596
}
597
```