0
# Plugin Descriptors
1

2
Metadata classes for describing plugins, mojos, and their parameters. Used by Maven tools, IDEs, and the runtime to understand plugin structure and configuration options.
3

4
## Capabilities
5

6
### PluginDescriptor Class
7

8
Describes a complete plugin with all its mojos and metadata. Contains plugin coordinates, goal prefix, and collection of MojoDescriptors.
9

10
```java { .api }
11
/**
12
 * Describes a complete Maven plugin with all its mojos and metadata
13
 */
14
public class PluginDescriptor extends ComponentSetDescriptor implements Cloneable {
15
    
16
    /**
17
     * Get the plugin's group ID
18
     * @return Maven group ID (e.g., "org.apache.maven.plugins")
19
     */
20
    public String getGroupId();
21
    
22
    /**
23
     * Set the plugin's group ID
24
     * @param groupId Maven group ID
25
     */
26
    public void setGroupId(String groupId);
27
    
28
    /**
29
     * Get the plugin's artifact ID
30
     * @return Maven artifact ID (e.g., "maven-compiler-plugin")
31
     */
32
    public String getArtifactId();
33
    
34
    /**
35
     * Set the plugin's artifact ID
36
     * @param artifactId Maven artifact ID
37
     */
38
    public void setArtifactId(String artifactId);
39
    
40
    /**
41
     * Get the plugin's version
42
     * @return plugin version string
43
     */
44
    public String getVersion();
45
    
46
    /**
47
     * Set the plugin's version
48
     * @param version plugin version string
49
     */
50
    public void setVersion(String version);
51
    
52
    /**
53
     * Get the plugin's goal prefix
54
     * @return goal prefix used to invoke plugin goals (e.g., "compiler")
55
     */
56
    public String getGoalPrefix();
57
    
58
    /**
59
     * Set the plugin's goal prefix
60
     * @param goalPrefix goal prefix for invoking goals
61
     */
62
    public void setGoalPrefix(String goalPrefix);
63
    
64
    /**
65
     * Get all mojos in this plugin
66
     * @return List of MojoDescriptor objects
67
     */
68
    public List<MojoDescriptor> getMojos();
69
    
70
    /**
71
     * Set the list of mojos for this plugin
72
     * @param mojos List of MojoDescriptor objects
73
     */
74
    public void setMojos(List<MojoDescriptor> mojos);
75
    
76
    /**
77
     * Find a specific mojo by goal name
78
     * @param goal the goal name to search for
79
     * @return MojoDescriptor for the goal, or null if not found
80
     */
81
    public MojoDescriptor getMojo(String goal);
82
    
83
    /**
84
     * Add a mojo to this plugin
85
     * @param mojoDescriptor the mojo descriptor to add
86
     * @throws DuplicateMojoDescriptorException if goal already exists
87
     */
88
    public void addMojo(MojoDescriptor mojoDescriptor) throws DuplicateMojoDescriptorException;
89
    
90
    /**
91
     * Create plugin key from coordinates
92
     * @param groupId plugin group ID
93
     * @param artifactId plugin artifact ID
94
     * @param version plugin version
95
     * @return plugin key string in format "groupId:artifactId:version"
96
     */
97
    public static String constructPluginKey(String groupId, String artifactId, String version);
98
    
99
    /**
100
     * Get plugin key for this descriptor
101
     * @return plugin key string
102
     */
103
    public String getPluginLookupKey();
104
    
105
    /**
106
     * Get plugin identifier with version
107
     * @return identifier string in format "groupId:artifactId:version"
108
     */
109
    public String getId();
110
    
111
    /**
112
     * Get the plugin name
113
     * @return human-readable plugin name
114
     */
115
    public String getName();
116
    
117
    /**
118
     * Set the plugin name
119
     * @param name human-readable plugin name
120
     */
121
    public void setName(String name);
122
    
123
    /**
124
     * Get the plugin description
125
     * @return description text
126
     */
127
    public String getDescription();
128
    
129
    /**
130
     * Set the plugin description
131
     * @param description description text
132
     */
133
    public void setDescription(String description);
134
    
135
    /**
136
     * Get the plugin source location
137
     * @return source file or URL
138
     */
139
    public String getSource();
140
    
141
    /**
142
     * Set the plugin source location
143
     * @param source source file or URL
144
     */
145
    public void setSource(String source);
146
    
147
    /**
148
     * Check if plugin is inherited by default in child projects
149
     * @return true if inherited by default
150
     */
151
    public boolean isInheritedByDefault();
152
    
153
    /**
154
     * Set whether plugin is inherited by default in child projects
155
     * @param inheritedByDefault true if inherited by default
156
     */
157
    public void setInheritedByDefault(boolean inheritedByDefault);
158
    
159
    /**
160
     * Get default plugin artifact ID from goal prefix
161
     * @param id goal prefix
162
     * @return artifact ID in format "maven-{id}-plugin"
163
     */
164
    public static String getDefaultPluginArtifactId(String id);
165
    
166
    /**
167
     * Get default plugin group ID
168
     * @return "org.apache.maven.plugins"
169
     */
170
    public static String getDefaultPluginGroupId();
171
    
172
    /**
173
     * Extract goal prefix from artifact ID
174
     * @param artifactId plugin artifact ID
175
     * @return extracted goal prefix
176
     */
177
    public static String getGoalPrefixFromArtifactId(String artifactId);
178
}
179
```
180

181
**Usage Example:**
182

183
```java
184
// Reading plugin descriptor from plugin.xml
185
PluginDescriptorBuilder builder = new PluginDescriptorBuilder();
186
try (FileReader reader = new FileReader("plugin.xml")) {
187
    PluginDescriptor descriptor = builder.build(reader);
188
    
189
    System.out.println("Plugin: " + descriptor.getId());
190
    System.out.println("Goal prefix: " + descriptor.getGoalPrefix());
191
    
192
    for (MojoDescriptor mojo : descriptor.getMojos()) {
193
        System.out.println("  Goal: " + mojo.getGoal());
194
        System.out.println("  Phase: " + mojo.getPhase());
195
    }
196
}
197
```
198

199
### MojoDescriptor Class
200

201
Describes individual Mojo metadata and configuration including goal name, execution phase, parameters, and behavioral flags.
202

203
```java { .api }
204
/**
205
 * Describes individual Mojo metadata and configuration
206
 */
207
public class MojoDescriptor extends ComponentDescriptor<Mojo> implements Cloneable {
208
    
209
    /** Execution strategy constant: "once-per-session" */
210
    public static final String SINGLE_PASS_EXEC_STRATEGY = "once-per-session";
211
    
212
    /** Execution strategy constant: "always" */
213
    public static final String MULTI_PASS_EXEC_STRATEGY = "always";
214
    
215
    /**
216
     * Get the goal name for this mojo
217
     * @return goal name (e.g., "compile", "test")
218
     */
219
    public String getGoal();
220
    
221
    /**
222
     * Set the goal name for this mojo
223
     * @param goal goal name
224
     */
225
    public void setGoal(String goal);
226
    
227
    /**
228
     * Get the default lifecycle phase for this mojo
229
     * @return lifecycle phase name (e.g., "compile", "test")
230
     */
231
    public String getPhase();
232
    
233
    /**
234
     * Set the default lifecycle phase for this mojo
235
     * @param phase lifecycle phase name
236
     */
237
    public void setPhase(String phase);
238
    
239
    /**
240
     * Get phase to execute before this mojo
241
     * @return phase name to execute first
242
     */
243
    public String getExecutePhase();
244
    
245
    /**
246
     * Set phase to execute before this mojo
247
     * @param executePhase phase name to execute first
248
     */
249
    public void setExecutePhase(String executePhase);
250
    
251
    /**
252
     * Get goal to execute before this mojo
253
     * @return goal name to execute first
254
     */
255
    public String getExecuteGoal();
256
    
257
    /**
258
     * Set goal to execute before this mojo
259
     * @param executeGoal goal name to execute first
260
     */
261
    public void setExecuteGoal(String executeGoal);
262
    
263
    /**
264
     * Get lifecycle to execute
265
     * @return lifecycle identifier
266
     */
267
    public String getExecuteLifecycle();
268
    
269
    /**
270
     * Set lifecycle to execute
271
     * @param executeLifecycle lifecycle identifier
272
     */
273
    public void setExecuteLifecycle(String executeLifecycle);
274
    
275
    /**
276
     * Get all parameters for this mojo
277
     * @return List of Parameter objects
278
     */
279
    public List<Parameter> getParameters();
280
    
281
    /**
282
     * Set the parameters for this mojo
283
     * @param parameters List of Parameter objects
284
     */
285
    public void setParameters(List<Parameter> parameters);
286
    
287
    /**
288
     * Get parameters as a name-keyed map
289
     * @return Map of parameter name to Parameter object
290
     */
291
    public Map<String, Parameter> getParameterMap();
292
    
293
    /**
294
     * Add a parameter to this mojo
295
     * @param parameter Parameter to add
296
     * @throws DuplicateParameterException if parameter name already exists
297
     */
298
    public void addParameter(Parameter parameter) throws DuplicateParameterException;
299
    
300
    /**
301
     * Check if this mojo is an aggregator
302
     * @return true if mojo aggregates across all projects
303
     */
304
    public boolean isAggregator();
305
    
306
    /**
307
     * Set whether this mojo is an aggregator
308
     * @param aggregator true if mojo should aggregate across projects
309
     */
310
    public void setAggregator(boolean aggregator);
311
    
312
    /**
313
     * Check if this mojo is thread-safe
314
     * @return true if mojo can run in parallel builds
315
     */
316
    public boolean isThreadSafe();
317
    
318
    /**
319
     * Set whether this mojo is thread-safe
320
     * @param threadSafe true if mojo can run in parallel
321
     */
322
    public void setThreadSafe(boolean threadSafe);
323
    
324
    /**
325
     * Check if inherited by default in sub-projects
326
     * @return true if inherited by default
327
     */
328
    public boolean isInheritedByDefault();
329
    
330
    /**
331
     * Set whether inherited by default in sub-projects
332
     * @param inheritedByDefault true if inherited by default
333
     */
334
    public void setInheritedByDefault(boolean inheritedByDefault);
335
    
336
    /**
337
     * Check if this mojo supports direct invocation only
338
     * @return true if can only be invoked directly (not bound to lifecycle)
339
     */
340
    public boolean isDirectInvocationOnly();
341
    
342
    /**
343
     * Set whether this mojo supports direct invocation only
344
     * @param directInvocationOnly true if direct invocation only
345
     */
346
    public void setDirectInvocationOnly(boolean directInvocationOnly);
347
    
348
    /**
349
     * Get dependency resolution requirement
350
     * @return dependency resolution scope required
351
     */
352
    public String getDependencyResolutionRequired();
353
    
354
    /**
355
     * Set dependency resolution requirement
356
     * @param requiresDependencyResolution dependency resolution scope
357
     */
358
    public void setDependencyResolutionRequired(String requiresDependencyResolution);
359
    
360
    /**
361
     * Get dependency collection requirement
362
     * @return dependency collection scope required
363
     * @since 3.0-alpha-3
364
     */
365
    public String getDependencyCollectionRequired();
366
    
367
    /**
368
     * Set dependency collection requirement
369
     * @param requiresDependencyCollection dependency collection scope
370
     * @since 3.0-alpha-3
371
     */
372
    public void setDependencyCollectionRequired(String requiresDependencyCollection);
373
    
374
    /**
375
     * Get the execution strategy
376
     * @return execution strategy (SINGLE_PASS_EXEC_STRATEGY or MULTI_PASS_EXEC_STRATEGY)
377
     */
378
    public String getExecutionStrategy();
379
    
380
    /**
381
     * Set the execution strategy
382
     * @param executionStrategy execution strategy
383
     */
384
    public void setExecutionStrategy(String executionStrategy);
385
    
386
    /**
387
     * Get the mojo language
388
     * @return language (e.g., "java")
389
     */
390
    public String getLanguage();
391
    
392
    /**
393
     * Set the mojo language
394
     * @param language language (e.g., "java")
395
     */
396
    public void setLanguage(String language);
397
    
398
    /**
399
     * Check if reports are required
400
     * @return true if reports are required
401
     */
402
    public boolean isRequiresReports();
403
    
404
    /**
405
     * Set whether reports are required
406
     * @param requiresReports true if reports are required
407
     */
408
    public void setRequiresReports(boolean requiresReports);
409
    
410
    /**
411
     * Get project requirement
412
     * @return true if project object is required
413
     */
414
    public boolean isProjectRequired();
415
    
416
    /**
417
     * Set project requirement
418
     * @param requiresProject true if project object is required
419
     */
420
    public void setProjectRequired(boolean requiresProject);
421
    
422
    /**
423
     * Get online requirement
424
     * @return true if network access is required
425
     */
426
    public boolean isOnlineRequired();
427
    
428
    /**
429
     * Set online requirement
430
     * @param requiresOnline true if network access is required
431
     */
432
    public void setOnlineRequired(boolean requiresOnline);
433
    
434
    /**
435
     * Get the version since this mojo was added
436
     * @return version string
437
     */
438
    public String getSince();
439
    
440
    /**
441
     * Set the version since this mojo was added
442
     * @param since version string
443
     */
444
    public void setSince(String since);
445
    
446
    /**
447
     * Get deprecation message
448
     * @return deprecation message or null if not deprecated
449
     */
450
    public String getDeprecated();
451
    
452
    /**
453
     * Set deprecation message
454
     * @param deprecated deprecation message
455
     */
456
    public void setDeprecated(String deprecated);
457
    
458
    /**
459
     * Get mojo description
460
     * @return description text
461
     */
462
    public String getDescription();
463
    
464
    /**
465
     * Set mojo description
466
     * @param description description text
467
     */
468
    public void setDescription(String description);
469
}
470
```
471

472
### Parameter Class
473

474
Describes individual mojo parameters including name, type, requirements, and default values.
475

476
```java { .api }
477
/**
478
 * Describes individual mojo parameters
479
 */
480
public class Parameter implements Cloneable {
481
    
482
    /**
483
     * Get parameter name
484
     * @return parameter name used in configuration
485
     */
486
    public String getName();
487
    
488
    /**
489
     * Set parameter name
490
     * @param name parameter name
491
     */
492
    public void setName(String name);
493
    
494
    /**
495
     * Get parameter alias
496
     * @return alternative name for this parameter
497
     */
498
    public String getAlias();
499
    
500
    /**
501
     * Set parameter alias
502
     * @param alias alternative name for this parameter
503
     */
504
    public void setAlias(String alias);
505
    
506
    /**
507
     * Get parameter type
508
     * @return Java type name (e.g., "java.lang.String", "java.io.File")
509
     */
510
    public String getType();
511
    
512
    /**
513
     * Set parameter type
514
     * @param type Java type name
515
     */
516
    public void setType(String type);
517
    
518
    /**
519
     * Check if parameter is required
520
     * @return true if parameter must be provided
521
     */
522
    public boolean isRequired();
523
    
524
    /**
525
     * Set whether parameter is required
526
     * @param required true if parameter must be provided
527
     */
528
    public void setRequired(boolean required);
529
    
530
    /**
531
     * Check if parameter is editable
532
     * @return true if parameter can be configured by users
533
     */
534
    public boolean isEditable();
535
    
536
    /**
537
     * Set whether parameter is editable
538
     * @param editable true if parameter can be configured
539
     */
540
    public void setEditable(boolean editable);
541
    
542
    /**
543
     * Get parameter description
544
     * @return description text for documentation
545
     */
546
    public String getDescription();
547
    
548
    /**
549
     * Set parameter description
550
     * @param description description text
551
     */
552
    public void setDescription(String description);
553
    
554
    /**
555
     * Get expression for property-based injection
556
     * @return expression string (e.g., "${project.build.directory}")
557
     */
558
    public String getExpression();
559
    
560
    /**
561
     * Set expression for property-based injection
562
     * @param expression expression string
563
     */
564
    public void setExpression(String expression);
565
    
566
    /**
567
     * Get default value
568
     * @return default value as string
569
     */
570
    public String getDefaultValue();
571
    
572
    /**
573
     * Set default value
574
     * @param defaultValue default value as string
575
     */
576
    public void setDefaultValue(String defaultValue);
577
    
578
    /**
579
     * Get implementation hint for dependency injection
580
     * @return implementation class name
581
     */
582
    public String getImplementation();
583
    
584
    /**
585
     * Set implementation hint for dependency injection
586
     * @param implementation implementation class name
587
     */
588
    public void setImplementation(String implementation);
589
    
590
    /**
591
     * Get component requirement
592
     * @return Requirement object for dependency injection
593
     */
594
    public Requirement getRequirement();
595
    
596
    /**
597
     * Set component requirement
598
     * @param requirement Requirement object for dependency injection
599
     */
600
    public void setRequirement(Requirement requirement);
601
    
602
    /**
603
     * Get since version
604
     * @return version when parameter was added
605
     */
606
    public String getSince();
607
    
608
    /**
609
     * Set since version
610
     * @param since version when parameter was added
611
     */
612
    public void setSince(String since);
613
    
614
    /**
615
     * Get deprecation message
616
     * @return deprecation message or null if not deprecated
617
     */
618
    public String getDeprecated();
619
    
620
    /**
621
     * Set deprecation message
622
     * @param deprecated deprecation message
623
     */
624
    public void setDeprecated(String deprecated);
625
    
626
    /**
627
     * Create a shallow copy of this parameter
628
     * @return cloned Parameter instance
629
     */
630
    public Parameter clone();
631
}
632
```
633

634
### Requirement Class
635

636
Describes component requirements/dependencies for dependency injection. This is an immutable class initialized through constructors.
637

638
```java { .api }
639
/**
640
 * Describes component requirements for dependency injection (immutable)
641
 */
642
public class Requirement implements Cloneable {
643
    
644
    /**
645
     * Create requirement with role only
646
     * @param role fully-qualified interface or class name
647
     */
648
    public Requirement(String role);
649
    
650
    /**
651
     * Create requirement with role and hint
652
     * @param role fully-qualified interface or class name
653
     * @param roleHint role hint for distinguishing implementations
654
     */
655
    public Requirement(String role, String roleHint);
656
    
657
    /**
658
     * Get component role
659
     * @return fully-qualified interface or class name
660
     */
661
    public String getRole();
662
    
663
    /**
664
     * Get role hint for distinguishing implementations
665
     * @return role hint string or null if not specified
666
     */
667
    public String getRoleHint();
668
    
669
    /**
670
     * Create a shallow copy of this requirement
671
     * @return cloned Requirement instance
672
     */
673
    public Requirement clone();
674
}
675
```
676

677
### PluginDescriptorBuilder Class
678

679
Builds PluginDescriptor objects from plugin.xml files, converting XML metadata into Java objects.
680

681
```java { .api }
682
/**
683
 * Builds PluginDescriptor objects from plugin.xml files
684
 */
685
public class PluginDescriptorBuilder {
686
    
687
    /**
688
     * Build PluginDescriptor from plugin.xml reader
689
     * @param reader Reader for plugin.xml content
690
     * @return PluginDescriptor object
691
     * @throws PlexusConfigurationException if XML is invalid
692
     */
693
    public PluginDescriptor build(Reader reader) throws PlexusConfigurationException;
694
    
695
    /**
696
     * Build PluginDescriptor from plugin.xml reader with source tracking
697
     * @param reader Reader for plugin.xml content  
698
     * @param source source identifier for error reporting
699
     * @return PluginDescriptor object
700
     * @throws PlexusConfigurationException if XML is invalid
701
     */
702
    public PluginDescriptor build(Reader reader, String source) throws PlexusConfigurationException;
703
}
704
```
705

706
**Usage Example:**
707

708
```java
709
// Build descriptor from plugin.xml
710
PluginDescriptorBuilder builder = new PluginDescriptorBuilder();
711
try (FileReader reader = new FileReader("src/main/resources/META-INF/maven/plugin.xml")) {
712
    PluginDescriptor descriptor = builder.build(reader, "plugin.xml");
713
    
714
    // Access plugin metadata
715
    System.out.println("Plugin: " + descriptor.getArtifactId());
716
    System.out.println("Version: " + descriptor.getVersion());
717
    System.out.println("Goals:");
718
    
719
    for (MojoDescriptor mojo : descriptor.getMojos()) {
720
        System.out.println("  " + mojo.getGoal() + " (phase: " + mojo.getPhase() + ")");
721
        
722
        for (Parameter param : mojo.getParameters()) {
723
            System.out.println("    Parameter: " + param.getName() + 
724
                             " (" + param.getType() + ")" +
725
                             (param.isRequired() ? " [required]" : ""));
726
        }
727
    }
728
}
729
```
730

731
## Descriptor Exception Classes
732

733
Exception classes for handling errors during descriptor parsing and validation.
734

735
### InvalidPluginDescriptorException
736

737
Base exception for plugin descriptor problems.
738

739
```java { .api }
740
/**
741
 * Base exception for plugin descriptor problems
742
 */
743
public class InvalidPluginDescriptorException extends PlexusConfigurationException {
744
    public InvalidPluginDescriptorException(String message);
745
    public InvalidPluginDescriptorException(String message, Throwable cause);
746
}
747
```
748

749
### DuplicateMojoDescriptorException
750

751
Thrown when duplicate mojo goals are found in a plugin.
752

753
```java { .api }
754
/**
755
 * Exception for duplicate mojo goals in a plugin
756
 */
757
public class DuplicateMojoDescriptorException extends InvalidPluginDescriptorException {
758
    public DuplicateMojoDescriptorException(String goalName);
759
}
760
```
761

762
### DuplicateParameterException
763

764
Thrown when duplicate parameter names are found in a mojo.
765

766
```java { .api }
767
/**
768
 * Exception for duplicate parameter names in a mojo
769
 */
770
public class DuplicateParameterException extends InvalidPluginDescriptorException {
771
    public DuplicateParameterException(String parameterName);
772
}
773
```
774

775
### InvalidParameterException
776

777
Thrown when invalid parameter definitions are encountered.
778

779
```java { .api }
780
/**
781
 * Exception for invalid parameter definitions
782
 */
783
public class InvalidParameterException extends InvalidPluginDescriptorException {
784
    public InvalidParameterException(String message, Throwable cause);
785
}
786
```
787

788
## Working with Descriptors
789

790
### Creating Plugin Descriptors Programmatically
791

792
```java
793
PluginDescriptor plugin = new PluginDescriptor();
794
plugin.setGroupId("com.example");
795
plugin.setArtifactId("my-maven-plugin");
796
plugin.setVersion("1.0.0");
797
plugin.setGoalPrefix("example");
798

799
MojoDescriptor mojo = new MojoDescriptor();
800
mojo.setGoal("process");
801
mojo.setPhase("compile");
802
mojo.setImplementation("com.example.ProcessMojo");
803

804
Parameter param = new Parameter();
805
param.setName("inputDir");
806
param.setType("java.io.File");
807
param.setRequired(true);
808
param.setExpression("${project.build.sourceDirectory}");
809
param.setDescription("Input directory to process");
810

811
mojo.addParameter(param);
812
plugin.addMojo(mojo);
813
```
814

815
### Reading Existing Descriptors
816

817
```java
818
// Parse plugin.xml from classpath
819
InputStream stream = getClass().getResourceAsStream("/META-INF/maven/plugin.xml");
820
PluginDescriptor descriptor = new PluginDescriptorBuilder()
821
    .build(new InputStreamReader(stream), "plugin.xml");
822

823
// Find specific mojo
824
MojoDescriptor processMojo = descriptor.getMojo("process");
825
if (processMojo != null) {
826
    System.out.println("Process mojo found in phase: " + processMojo.getPhase());
827
    
828
    // Check parameters
829
    Map<String, Parameter> params = processMojo.getParameterMap();
830
    if (params.containsKey("inputDir")) {
831
        Parameter inputDir = params.get("inputDir");
832
        System.out.println("Input dir type: " + inputDir.getType());
833
        System.out.println("Input dir required: " + inputDir.isRequired());
834
    }
835
}
836
```