Exception Handling

/**
 * Base class for Mojo execution exceptions
 */
public abstract class AbstractMojoExecutionException extends Exception {
    protected Object source;
    protected String longMessage;
    
    /**
     * Get the detailed error message for build output
     * @return long-form error message or null if not set
     */
    public String getLongMessage();
    
    /**
     * Get the source object that caused this exception
     * @return source object or null if not set
     */
    public Object getSource();
}

/**
 * Exception for unexpected problems during Mojo execution.
 * Results in "BUILD ERROR" message.
 */
public class MojoExecutionException extends AbstractMojoExecutionException {
    
    /**
     * Create exception with simple message
     * @param message error description
     */
    public MojoExecutionException(String message);
    
    /**
     * Create exception wrapping another Exception with message
     * @param message error description
     * @param cause underlying Exception
     */
    public MojoExecutionException(String message, Exception cause);
    
    /**
     * Create exception wrapping Throwable with message
     * @param message error description
     * @param cause underlying Throwable
     */
    public MojoExecutionException(String message, Throwable cause);
    
    /**
     * Create exception with source tracking and detailed messages for build output
     * @param source object that caused the error
     * @param shortMessage brief error description
     * @param longMessage detailed error information for build output
     */
    public MojoExecutionException(Object source, String shortMessage, String longMessage);
    
    /**
     * Create exception wrapping Throwable (cause saved for getCause())
     * @param cause underlying Throwable
     * @since 3.8.3
     */
    public MojoExecutionException(Throwable cause);
}

// Simple error message
throw new MojoExecutionException("Failed to read configuration file");

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

// With detailed build output
throw new MojoExecutionException(
    this,
    "Configuration invalid",
    "The plugin configuration contains invalid values:\n" +
    "- outputDirectory must be an absolute path\n" +
    "- encoding must be a valid charset name\n" +
    "Please correct these issues and try again."
);

/**
 * Exception for expected problems like compilation failures.
 * Results in "BUILD FAILURE" message.
 */
public class MojoFailureException extends AbstractMojoExecutionException {
    
    /**
     * Create exception with simple message
     * @param message failure description
     */
    public MojoFailureException(String message);
    
    /**
     * Create exception wrapping Throwable with message
     * @param message failure description
     * @param cause underlying Throwable
     */
    public MojoFailureException(String message, Throwable cause);
    
    /**
     * Create exception with source tracking and detailed messages for build output
     * @param source object that caused the failure
     * @param shortMessage brief failure description
     * @param longMessage detailed failure information for build output
     */
    public MojoFailureException(Object source, String shortMessage, String longMessage);
    
    /**
     * Create exception wrapping Throwable (cause saved for getCause())
     * @param cause underlying Throwable
     */
    public MojoFailureException(Throwable cause);
}

// Validation failure
if (!sourceDirectory.exists()) {
    throw new MojoFailureException("Source directory does not exist: " + sourceDirectory);
}

// Compilation-like failure with detailed output
if (hasValidationErrors) {
    throw new MojoFailureException(
        this,
        "Code quality checks failed",
        "Found " + errorCount + " code quality violations:\n" +
        validationErrors.stream()
            .map(error -> "  " + error.getFile() + ":" + error.getLine() + " - " + error.getMessage())
            .collect(Collectors.joining("\n"))
    );
}

// Wrapping a domain-specific exception
try {
    validator.validate(sourceFiles);
} catch (ValidationException e) {
    throw new MojoFailureException("Code validation failed", e);
}

/**
 * Exception for missing goals in plugins
 */
public class MojoNotFoundException extends Exception {
    
    /**
     * Create exception for missing goal
     * @param goal the goal name that was not found
     * @param pluginDescriptor descriptor of the plugin searched
     */
    public MojoNotFoundException(String goal, PluginDescriptor pluginDescriptor);
    
    /**
     * Get the goal name that was not found
     * @return missing goal name
     */
    public String getGoal();
    
    /**
     * Get the plugin descriptor that was searched
     * @return plugin descriptor
     */
    public PluginDescriptor getPluginDescriptor();
}

// System failure example
try {
    Process process = new ProcessBuilder("external-tool").start();
    int exitCode = process.waitFor();
    if (exitCode != 0) {
        throw new MojoExecutionException("External tool failed with exit code: " + exitCode);
    }
} catch (IOException | InterruptedException e) {
    throw new MojoExecutionException("Failed to execute external tool", e);
}

// User configuration error example
if (outputFormat != null && !SUPPORTED_FORMATS.contains(outputFormat)) {
    throw new MojoFailureException(
        "Unsupported output format: " + outputFormat + 
        ". Supported formats are: " + SUPPORTED_FORMATS
    );
}

// Business logic failure example  
if (duplicateClasses.size() > 0) {
    throw new MojoFailureException(
        "Found duplicate classes in classpath:\n" +
        duplicateClasses.stream()
            .map(cls -> "  " + cls)
            .collect(Collectors.joining("\n"))
    );
}

// Good error message
throw new MojoFailureException(
    this,
    "Invalid target directory", 
    "The target directory '" + targetDir + "' is not writable.\n" +
    "Please check that:\n" +
    "1. The directory exists and is writable\n" +
    "2. Your user has appropriate permissions\n" +
    "3. The disk is not full"
);

// Poor error message
throw new MojoFailureException("Directory error");