Merge remote-tracking branch

'origin/GP-2982-dragonmacher-task-monitor-api' (Closes #4870)

Ghidra/Framework/Generic/src/main/java/ghidra/util/task/TaskMonitorAdapter.java

@@ -20,11 +20,10 @@ import ghidra.util.datastruct.WeakSet;
 import ghidra.util.exception.CancelledException;
 
 /**
- * Create a "do nothing" task monitor that we can pass along to methods that
+ * Implementation of {@link TaskMonitor} with most features stubbed out.
- * need a task monitor. This can be used when methods provide detailed
+ * <p>
- * task progress information that we don't want to show the user.
+ * This class supports cancelling and cancel listener notification.  Cancelling must be enabled
- * <P>This  monitor can be configured to allow cancelling via {@link #setCancelEnabled(boolean)}.
+ * via {@link #setCancelEnabled(boolean)}.
- * If this cancelling is enabled, the the monitor may be cancelled programmatically.
  */
 public class TaskMonitorAdapter implements TaskMonitor {
 
@@ -145,7 +144,7 @@ public class TaskMonitorAdapter implements TaskMonitor {
 			cancelled = false;
 		}
 
-		// TODO this seems like a mistake, to notify of 'cancelled' when clearning 
+		// TODO this seems like a mistake, to notify of 'cancelled' when clearing
 		notifyChangeListeners();
 	}
 

Ghidra/Framework/Utility/src/main/java/ghidra/util/task/TaskMonitor.java

@@ -18,22 +18,24 @@ package ghidra.util.task;
 import ghidra.util.exception.CancelledException;
 
 /**
- * <CODE>TaskMonitor</CODE> provides an interface by means of which a
+ * <CODE>TaskMonitor</CODE> provides an interface that allows potentially long running tasks to show
- * potentially long running task can show its progress and also check if the user
+ * progress and check for user has cancellation.
- * has cancelled the operation. 
  * <p>
- * Operations that support a task monitor should periodically
+ * Tasks that support a task monitor should periodically check to see if the operation has been
- * check to see if the operation has been cancelled and abort. If possible, the 
+ * cancelled and abort. If possible, the task should also provide periodic progress information. If
- * operation should also provide periodic progress information. If it can estimate a 
+ * your task can estimate the amount of work done, then it should use the {@link #setProgress(long)}
- * percentage done, then it should use the <code>setProgress(int)</code> method, 
+ * method, otherwise it should call {@link #setMessage(String)} method to provide status updates.
- * otherwise it should just call the <code>setMessage(String)</code> method. 
  */
 public interface TaskMonitor {
 
+	/**
+	 * A 'do nothing' task monitor that can be passed to APIs when the client has not progress to
+	 * report.
+	 */
 	public static final TaskMonitor DUMMY = new StubTaskMonitor();
 
 	/**
-	 * Returns the given task monitor if it is not {@code null}.  Otherwise, a {@link #DUMMY} 
+	 * Returns the given task monitor if it is not {@code null}.  Otherwise, a {@link #DUMMY}
 	 * monitor is returned.
 	 * @param tm the monitor to check for {@code null}
 	 * @return a non-null task monitor
@@ -47,21 +49,21 @@ public interface TaskMonitor {
 
 	/**
 	 * Returns true if the user has cancelled the operation
-	 * 
+	 *
 	 * @return true if the user has cancelled the operation
 	 */
 	public boolean isCancelled();
 
 	/**
 	 * True (the default) signals to paint the progress information inside of the progress bar
-	 * 
+	 *
 	 * @param showProgressValue true to paint the progress value; false to not
 	 */
 	public void setShowProgressValue(boolean showProgressValue);
 
 	/**
 	 * Sets the message displayed on the task monitor
-	 * 
+	 *
 	 * @param message the message to display
 	 */
 	public void setMessage(String message);
@@ -81,7 +83,7 @@ public interface TaskMonitor {
 	/**
 	 * Initialized this TaskMonitor to the given max values.  The current value of this monitor
 	 * will be set to zero.
-	 * 
+	 *
 	 * @param max maximum value for progress
 	 */
 	public void initialize(long max);
@@ -95,14 +97,14 @@ public interface TaskMonitor {
 	 */
 	public void setMaximum(long max);
 
-	/** 
+	/**
 	 * Returns the current maximum value for progress
 	 * @return the maximum progress value
 	 */
 	public long getMaximum();
 
 	/**
-	 * An indeterminate task monitor may choose to show an animation instead of updating progress 
+	 * An indeterminate task monitor may choose to show an animation instead of updating progress
 	 * @param indeterminate true if indeterminate
 	 */
 	public void setIndeterminate(boolean indeterminate);
@@ -114,11 +116,22 @@ public interface TaskMonitor {
 	public boolean isIndeterminate();
 
 	/**
-	 * Check to see if this monitor has been canceled
+	 * (Use {@link #checkCancelled()} instead)
+	 *
+	 * Check to see if this monitor has been cancelled.
 	 * @throws CancelledException if monitor has been cancelled
 	 */
 	public void checkCanceled() throws CancelledException;
 
+	/**
+	 * Check to see if this monitor has been cancelled
+	 * @throws CancelledException if monitor has been cancelled
+	 */
+	public default void checkCancelled() throws CancelledException {
+		// note: call checkCanceled() until it is removed; this produces the least number of changes
+		checkCanceled();
+	}
+
 	/**
 	 * A convenience method to increment the current progress by the given value
 	 * @param incrementAmount The amount by which to increment the progress
@@ -126,10 +139,8 @@ public interface TaskMonitor {
 	public void incrementProgress(long incrementAmount);
 
 	/**
-	 * Returns the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value
+	 * Returns the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value set
-	 * set
+	 * @return the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value set
-	 * @return the current progress value or {@link #NO_PROGRESS_VALUE} if there is no value
-	 * set
 	 */
 	public long getProgress();
 
@@ -163,9 +174,17 @@ public interface TaskMonitor {
 	public boolean isCancelEnabled();
 
 	/**
+	 * (Use {@link #clearCancelled()} instead)
+	 * <p>
 	 * Clear the cancellation so that this TaskMonitor may be reused
-	 *
 	 */
 	public void clearCanceled();
 
+	/**
+	 * Clear the cancellation so that this TaskMonitor may be reused
+	 */
+	public default void clearCancelled() {
+		// note: call clearCanceled() until it is removed; this produces the least number of changes
+		clearCanceled();
+	}
 }