0
# Exception Handling
1

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

4
## Capabilities
5

6
### AbstractMojoExecutionException Base Class
7

8
Base class for all Mojo execution exceptions, providing source tracking and detailed error message support for improved Maven build output.
9

10
```java { .api }
11
/**
12
 * Base class for Mojo execution exceptions
13
 */
14
public abstract class AbstractMojoExecutionException extends Exception {
15
    protected Object source;
16
    protected String longMessage;
17
    
18
    /**
19
     * Get the detailed error message for build output
20
     * @return long-form error message or null if not set
21
     */
22
    public String getLongMessage();
23
    
24
    /**
25
     * Get the source object that caused this exception
26
     * @return source object or null if not set
27
     */
28
    public Object getSource();
29
}
30
```
31

32
### MojoExecutionException Class
33

34
Exception for unexpected problems during Mojo execution. Throwing this exception causes a "BUILD ERROR" message to be displayed, indicating system or infrastructure problems.
35

36
```java { .api }
37
/**
38
 * Exception for unexpected problems during Mojo execution.
39
 * Results in "BUILD ERROR" message.
40
 */
41
public class MojoExecutionException extends AbstractMojoExecutionException {
42
    
43
    /**
44
     * Create exception with simple message
45
     * @param message error description
46
     */
47
    public MojoExecutionException(String message);
48
    
49
    /**
50
     * Create exception wrapping another Exception with message
51
     * @param message error description
52
     * @param cause underlying Exception
53
     */
54
    public MojoExecutionException(String message, Exception cause);
55
    
56
    /**
57
     * Create exception wrapping Throwable with message
58
     * @param message error description
59
     * @param cause underlying Throwable
60
     */
61
    public MojoExecutionException(String message, Throwable cause);
62
    
63
    /**
64
     * Create exception with source tracking and detailed messages for build output
65
     * @param source object that caused the error
66
     * @param shortMessage brief error description
67
     * @param longMessage detailed error information for build output
68
     */
69
    public MojoExecutionException(Object source, String shortMessage, String longMessage);
70
    
71
    /**
72
     * Create exception wrapping Throwable (cause saved for getCause())
73
     * @param cause underlying Throwable
74
     * @since 3.8.3
75
     */
76
    public MojoExecutionException(Throwable cause);
77
}
78
```
79

80
**Usage Examples:**
81

82
```java
83
// Simple error message
84
throw new MojoExecutionException("Failed to read configuration file");
85

86
// With underlying cause
87
try {
88
    Files.copy(source, target);
89
} catch (IOException e) {
90
    throw new MojoExecutionException("Unable to copy file from " + source + " to " + target, e);
91
}
92

93
// With detailed build output
94
throw new MojoExecutionException(
95
    this,
96
    "Configuration invalid",
97
    "The plugin configuration contains invalid values:\n" +
98
    "- outputDirectory must be an absolute path\n" +
99
    "- encoding must be a valid charset name\n" +
100
    "Please correct these issues and try again."
101
);
102
```
103

104
### MojoFailureException Class
105

106
Exception for expected problems during Mojo execution, such as compilation failures or validation errors. Throwing this exception causes a "BUILD FAILURE" message, indicating user-correctable issues.
107

108
```java { .api }
109
/**
110
 * Exception for expected problems like compilation failures.
111
 * Results in "BUILD FAILURE" message.
112
 */
113
public class MojoFailureException extends AbstractMojoExecutionException {
114
    
115
    /**
116
     * Create exception with simple message
117
     * @param message failure description
118
     */
119
    public MojoFailureException(String message);
120
    
121
    /**
122
     * Create exception wrapping Throwable with message
123
     * @param message failure description
124
     * @param cause underlying Throwable
125
     */
126
    public MojoFailureException(String message, Throwable cause);
127
    
128
    /**
129
     * Create exception with source tracking and detailed messages for build output
130
     * @param source object that caused the failure
131
     * @param shortMessage brief failure description
132
     * @param longMessage detailed failure information for build output
133
     */
134
    public MojoFailureException(Object source, String shortMessage, String longMessage);
135
    
136
    /**
137
     * Create exception wrapping Throwable (cause saved for getCause())
138
     * @param cause underlying Throwable
139
     */
140
    public MojoFailureException(Throwable cause);
141
}
142
```
143

144
**Usage Examples:**
145

146
```java
147
// Validation failure
148
if (!sourceDirectory.exists()) {
149
    throw new MojoFailureException("Source directory does not exist: " + sourceDirectory);
150
}
151

152
// Compilation-like failure with detailed output
153
if (hasValidationErrors) {
154
    throw new MojoFailureException(
155
        this,
156
        "Code quality checks failed",
157
        "Found " + errorCount + " code quality violations:\n" +
158
        validationErrors.stream()
159
            .map(error -> "  " + error.getFile() + ":" + error.getLine() + " - " + error.getMessage())
160
            .collect(Collectors.joining("\n"))
161
    );
162
}
163

164
// Wrapping a domain-specific exception
165
try {
166
    validator.validate(sourceFiles);
167
} catch (ValidationException e) {
168
    throw new MojoFailureException("Code validation failed", e);
169
}
170
```
171

172
### MojoNotFoundException Class
173

174
Exception thrown when a requested goal cannot be found in a plugin. Used internally by Maven when goal resolution fails.
175

176
```java { .api }
177
/**
178
 * Exception for missing goals in plugins
179
 */
180
public class MojoNotFoundException extends Exception {
181
    
182
    /**
183
     * Create exception for missing goal
184
     * @param goal the goal name that was not found
185
     * @param pluginDescriptor descriptor of the plugin searched
186
     */
187
    public MojoNotFoundException(String goal, PluginDescriptor pluginDescriptor);
188
    
189
    /**
190
     * Get the goal name that was not found
191
     * @return missing goal name
192
     */
193
    public String getGoal();
194
    
195
    /**
196
     * Get the plugin descriptor that was searched
197
     * @return plugin descriptor
198
     */
199
    public PluginDescriptor getPluginDescriptor();
200
}
201
```
202

203
## Exception Handling Best Practices
204

205
### When to Use MojoExecutionException
206

207
- **System failures**: I/O errors, network issues, out of memory
208
- **Infrastructure problems**: Missing required tools, invalid Maven configuration
209
- **Unexpected runtime errors**: NullPointerException, ClassNotFoundException
210
- **Plugin bugs**: Logic errors in the plugin code itself
211

212
```java
213
// System failure example
214
try {
215
    Process process = new ProcessBuilder("external-tool").start();
216
    int exitCode = process.waitFor();
217
    if (exitCode != 0) {
218
        throw new MojoExecutionException("External tool failed with exit code: " + exitCode);
219
    }
220
} catch (IOException | InterruptedException e) {
221
    throw new MojoExecutionException("Failed to execute external tool", e);
222
}
223
```
224

225
### When to Use MojoFailureException
226

227
- **User configuration errors**: Invalid parameter values, missing required files
228
- **Build failures**: Compilation errors, test failures, code quality violations
229
- **Validation errors**: Schema validation, format validation
230
- **Business logic failures**: Domain-specific validation rules
231

232
```java
233
// User configuration error example
234
if (outputFormat != null && !SUPPORTED_FORMATS.contains(outputFormat)) {
235
    throw new MojoFailureException(
236
        "Unsupported output format: " + outputFormat + 
237
        ". Supported formats are: " + SUPPORTED_FORMATS
238
    );
239
}
240

241
// Business logic failure example  
242
if (duplicateClasses.size() > 0) {
243
    throw new MojoFailureException(
244
        "Found duplicate classes in classpath:\n" +
245
        duplicateClasses.stream()
246
            .map(cls -> "  " + cls)
247
            .collect(Collectors.joining("\n"))
248
    );
249
}
250
```
251

252
### Error Message Guidelines
253

254
1. **Be specific**: Include file paths, parameter names, and actual values
255
2. **Be helpful**: Suggest solutions when possible
256
3. **Use longMessage**: For detailed explanations in build output
257
4. **Include context**: What the plugin was trying to do when the error occurred
258

259
```java
260
// Good error message
261
throw new MojoFailureException(
262
    this,
263
    "Invalid target directory", 
264
    "The target directory '" + targetDir + "' is not writable.\n" +
265
    "Please check that:\n" +
266
    "1. The directory exists and is writable\n" +
267
    "2. Your user has appropriate permissions\n" +
268
    "3. The disk is not full"
269
);
270

271
// Poor error message
272
throw new MojoFailureException("Directory error");
273
```