From 91c6e4eab88622ef223187db9f92f336445f8cea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christoph=20L=C3=A4ubrich?= <christoph@laeubi-soft.de>
Date: Sun, 14 Sep 2025 17:45:04 +0200
Subject: [PATCH] Add a Progress API

Fix https://github.com/codehaus-plexus/plexus-build-api/issues/52
Fix https://github.com/codehaus-plexus/plexus-build-api/issues/56
---
 README.md                                     |  5 ++
 .../build/progress/DefaultProgress.java       | 64 +++++++++++++++++++
 .../plexus/build/progress/Progress.java       | 48 ++++++++++++++
 3 files changed, 117 insertions(+)
 create mode 100644 src/main/java/org/codehaus/plexus/build/progress/DefaultProgress.java
 create mode 100644 src/main/java/org/codehaus/plexus/build/progress/Progress.java

diff --git a/README.md b/README.md
index 1789d9f..189be68 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,11 @@ The project was relocated from <https://github.com/sonatype/sisu-build-api>. Als
 
 ## Provided APIs
 
+### Progress
+
+The API allows a mojo to report progress in a way that is suitable to be shown as a progressbar as well as check if the user wants the mojo to gracefully abort its current operation.
+This can be useful for example when processing some files in a loop so the user can directly see the amount of progress and possibly ask to abort if it takes to long.
+
 ### IDE connection to maven process
 
 This API is usually not used by mojos but for IDE integration, if enabled as a maven-core extension plexus-build-api supply a way to communicate with the running maven build and get events.
diff --git a/src/main/java/org/codehaus/plexus/build/progress/DefaultProgress.java b/src/main/java/org/codehaus/plexus/build/progress/DefaultProgress.java
new file mode 100644
index 0000000..e912c3f
--- /dev/null
+++ b/src/main/java/org/codehaus/plexus/build/progress/DefaultProgress.java
@@ -0,0 +1,64 @@
+package org.codehaus.plexus.build.progress;
+
+import javax.inject.Inject;
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import org.apache.maven.execution.scope.MojoExecutionScoped;
+import org.apache.maven.plugin.MojoExecution;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The default implementation simply log to debug and check for thread
+ * interruption
+ */
+@Named("default")
+@Singleton
+@MojoExecutionScoped
+public class DefaultProgress implements Progress {
+
+    private final Logger logger = LoggerFactory.getLogger(DefaultProgress.class);
+    private MojoExecution execution;
+    private int work;
+
+    @Inject
+    public DefaultProgress(MojoExecution execution) {
+        this.execution = execution;
+    }
+
+    @Override
+    public void startTask(String task, int work) {
+        setRemaining(work);
+        logger.debug(execution.getExecutionId() + ": " + task);
+    }
+
+    @Override
+    public void worked(int work) {
+        if (work == 0) {
+            return;
+        }
+        if (work < 0) {
+            logger.warn(execution.getExecutionId() + " reported negative amount of work!");
+        }
+        if (this.work < 0) {
+            return;
+        }
+        if (work > this.work) {
+            this.work = -1;
+            logger.warn(execution.getExecutionId() + " reported more work than expected!");
+        } else {
+            this.work -= work;
+        }
+    }
+
+    @Override
+    public void setRemaining(int work) {
+        this.work = work <= 0 ? -1 : work;
+    }
+
+    @Override
+    public boolean isCancelRequested() {
+        return Thread.currentThread().isInterrupted();
+    }
+}
diff --git a/src/main/java/org/codehaus/plexus/build/progress/Progress.java b/src/main/java/org/codehaus/plexus/build/progress/Progress.java
new file mode 100644
index 0000000..27c3427
--- /dev/null
+++ b/src/main/java/org/codehaus/plexus/build/progress/Progress.java
@@ -0,0 +1,48 @@
+package org.codehaus.plexus.build.progress;
+
+/**
+ * The {@link Progress} allows a mojo to report its current state and check if
+ * the user has requested cancellation.
+ */
+public interface Progress {
+
+    /**
+     * Reports that the mojo has started the given task with the given amount of
+     * work.
+     *
+     * @param task
+     * @param work the amount of work that the mojo plan to report, if a value
+     *             <code>&lt;= 0</code> is given the amount of work is assumed to be
+     *             unknown.
+     */
+    void startTask(String task, int work);
+
+    /**
+     * Reports a given amount of work was processed
+     *
+     * @param work
+     */
+    void worked(int work);
+
+    /**
+     * Reports one unit of work to be processed
+     */
+    default void worked() {
+        worked(1);
+    }
+
+    /**
+     * Notifies the remaining amount of work that will be reported
+     *
+     * @param work
+     */
+    void setRemaining(int work);
+
+    /**
+     * This method should be used to check if the user has requested to finish the
+     * current work and break out early.
+     *
+     * @return <code>true</code> if a cancel request is currently pending.
+     */
+    boolean isCancelRequested();
+}