0
# Maven Plugin API
1

2
The API for plugins - Mojos - development. This library provides the core interfaces, classes, and abstractions needed to develop Maven plugins that extend Maven's functionality during the build lifecycle.
3

4
## Package Information
5

6
- **Package Name**: org.apache.maven:maven-plugin-api
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml` dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>org.apache.maven</groupId>
14
    <artifactId>maven-plugin-api</artifactId>
15
    <version>3.9.11</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import org.apache.maven.plugin.Mojo;
23
import org.apache.maven.plugin.AbstractMojo;
24
import org.apache.maven.plugin.MojoExecutionException;
25
import org.apache.maven.plugin.MojoFailureException;
26
import org.apache.maven.plugin.logging.Log;
27
import org.apache.maven.plugin.descriptor.PluginDescriptor;
28
import org.apache.maven.plugin.descriptor.MojoDescriptor;
29
import org.apache.maven.monitor.logging.DefaultLog;
30
```
31

32
## Basic Usage
33

34
```java
35
import org.apache.maven.plugin.AbstractMojo;
36
import org.apache.maven.plugin.MojoExecutionException;
37
import org.apache.maven.plugin.MojoFailureException;
38

39
/**
40
 * Example Maven plugin that demonstrates basic usage
41
 * @goal hello
42
 */
43
public class HelloMojo extends AbstractMojo {
44
    
45
    /**
46
     * @parameter property="greeting" default-value="Hello World!"
47
     */
48
    private String greeting;
49
    
50
    @Override
51
    public void execute() throws MojoExecutionException, MojoFailureException {
52
        Log log = getLog();
53
        log.info(greeting);
54
        
55
        try {
56
            // Plugin logic here
57
            log.debug("Executing hello goal");
58
        } catch (Exception e) {
59
            throw new MojoExecutionException("Unexpected error", e);
60
        }
61
    }
62
}
63
```
64

65
## Architecture
66

67
The Maven Plugin API is built around several key components:
68

69
- **Mojo Interface**: The contract that all Maven plugins must implement to interact with Maven
70
- **AbstractMojo**: Base class providing infrastructure like logging and context management
71
- **Exception Hierarchy**: Distinguishes between unexpected errors (MojoExecutionException) and expected failures (MojoFailureException)
72
- **Logging System**: Standardized logging interface that integrates with Maven's output system
73
- **Descriptor System**: Metadata classes that describe plugins, mojos, and their parameters for tooling and runtime
74

75
## Capabilities
76

77
### Core Plugin Development
78

79
Essential interfaces and base classes for creating Maven plugins. Provides the fundamental Mojo contract and ready-to-use AbstractMojo base class with logging and context support.
80

81
```java { .api }
82
public interface Mojo {
83
    String ROLE = Mojo.class.getName();
84
    void execute() throws MojoExecutionException, MojoFailureException;
85
    void setLog(Log log);
86
    Log getLog();
87
}
88

89
public abstract class AbstractMojo implements Mojo, ContextEnabled {
90
    public void setLog(Log log);
91
    public Log getLog();
92
    public Map getPluginContext();
93
    public void setPluginContext(Map pluginContext);
94
}
95
```
96

97
[Core Plugin Development](./core-plugin-development.md)
98

99
### Exception Handling
100

101
Exception classes for proper error reporting during plugin execution. Distinguishes between unexpected errors and expected failures to provide appropriate Maven build messages.
102

103
```java { .api }
104
public class MojoExecutionException extends AbstractMojoExecutionException {
105
    public MojoExecutionException(String message);
106
    public MojoExecutionException(String message, Exception cause);
107
    public MojoExecutionException(String message, Throwable cause);
108
    public MojoExecutionException(Object source, String shortMessage, String longMessage);
109
}
110

111
public class MojoFailureException extends AbstractMojoExecutionException {
112
    public MojoFailureException(String message);
113
    public MojoFailureException(String message, Throwable cause);
114
    public MojoFailureException(Object source, String shortMessage, String longMessage);
115
}
116

117
public class MojoNotFoundException extends Exception {
118
    public MojoNotFoundException(String goal, PluginDescriptor pluginDescriptor);
119
    public String getGoal();
120
    public PluginDescriptor getPluginDescriptor();
121
}
122
```
123

124
[Exception Handling](./exception-handling.md)
125

126
### Logging System
127

128
Standardized logging interface for Maven plugins with support for debug, info, warn, and error levels. Integrates with Maven's output system and supports both message-only and message-with-throwable logging.
129

130
```java { .api }
131
public interface Log {
132
    boolean isDebugEnabled();
133
    void debug(CharSequence content);
134
    void debug(CharSequence content, Throwable error);
135
    void debug(Throwable error);
136
    
137
    boolean isInfoEnabled();
138
    void info(CharSequence content);
139
    void info(CharSequence content, Throwable error);
140
    void info(Throwable error);
141
    
142
    boolean isWarnEnabled();
143
    void warn(CharSequence content);
144
    void warn(CharSequence content, Throwable error);
145
    void warn(Throwable error);
146
    
147
    boolean isErrorEnabled();
148
    void error(CharSequence content);
149
    void error(CharSequence content, Throwable error);
150
    void error(Throwable error);
151
}
152
```
153

154
[Logging System](./logging-system.md)
155

156
### Plugin Descriptors
157

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

160
```java { .api }
161
public class PluginDescriptor extends ComponentSetDescriptor implements Cloneable {
162
    public String getGroupId();
163
    public String getArtifactId();
164
    public String getVersion();
165
    public String getGoalPrefix();
166
    public List<MojoDescriptor> getMojos();
167
    public MojoDescriptor getMojo(String goal);
168
    public void addMojo(MojoDescriptor mojoDescriptor) throws DuplicateMojoDescriptorException;
169
}
170

171
public class MojoDescriptor extends ComponentDescriptor<Mojo> implements Cloneable {
172
    public static final String SINGLE_PASS_EXEC_STRATEGY = "once-per-session";
173
    public static final String MULTI_PASS_EXEC_STRATEGY = "always";
174
    
175
    public String getGoal();
176
    public String getPhase();
177
    public List<Parameter> getParameters();
178
    public Map<String, Parameter> getParameterMap();
179
}
180
```
181

182
[Plugin Descriptors](./plugin-descriptors.md)
183

184
## Types
185

186
```java { .api }
187
public interface ContextEnabled {
188
    void setPluginContext(Map pluginContext);
189
    Map getPluginContext();
190
}
191

192
public abstract class AbstractMojoExecutionException extends Exception {
193
    protected Object source;
194
    protected String longMessage;
195
    
196
    public String getLongMessage();
197
    public Object getSource();
198
}
199

200
public class SystemStreamLog implements Log {
201
    // Default Log implementation using System.out and System.err
202
}
203

204
public class DefaultLog implements Log {
205
    /**
206
     * Create DefaultLog wrapping Plexus logger
207
     * @param logger Plexus logger instance
208
     */
209
    public DefaultLog(Logger logger);
210
}
211
```