Merge pull request #124 from jglick/retry-unconditionally-JENKINS-49707

[JENKINS-49707] Recommend `BodyExecution.cancel` overload taking `Throwable`

Author: jglick

src/main/java/org/jenkinsci/plugins/workflow/steps/BodyExecution.java

@@ -23,6 +23,8 @@
  */
 package org.jenkinsci.plugins.workflow.steps;
 
+import hudson.Util;
+import hudson.model.Result;
 import jenkins.model.CauseOfInterruption;
 
 import java.io.Serializable;
@@ -49,31 +51,41 @@ public abstract class BodyExecution implements Future<Object>, Serializable {
     public abstract Collection<StepExecution> getCurrentExecutions();
 
     /**
-     * Attempts to cancel an executing body block.
-     *
-     * <p>
-     * If the body has finished executing, or is cancelled already, the attempt will
-     * fail. This method is asynchronous. There's no guarantee that the cancellation
-     * has happened or completed before this method returns.
-     *
-     * @return false if the task cannot be cancelled.
+     * @deprecated use {@link #cancel(Throwable)} with {@link FlowInterruptedException}
      */
-    public abstract boolean cancel(CauseOfInterruption... causes);
+    @Deprecated
+    public boolean cancel(CauseOfInterruption... causes) {
+        if (Util.isOverridden(BodyExecution.class, getClass(), "cancel", Throwable.class)) {
+            return cancel(new FlowInterruptedException(Result.ABORTED, true, causes));
+        } else {
+            throw new AbstractMethodError("Override cancel(Throwable) from " + getClass());
+        }
+    }
 
     /**
-     * @deprecated
-     *      Use other overloaded forms of the cancel method to provide richer context.
+     * @deprecated use {@link #cancel(Throwable)} to provide richer context
      */
+    @Deprecated
     public boolean cancel(boolean b) {
-        return cancel(new Exception());
+        return cancel(new FlowInterruptedException(Result.ABORTED, true));
     }
 
     /**
-     * Convenience method around {@link #cancel(CauseOfInterruption...)} in case
-     * the cause is a random exception.
+     * Attempts to cancel an executing body block.
+     *
+     * <p>
+     * If the body has finished executing, or is cancelled already, the attempt will
+     * fail. This method is asynchronous. There's no guarantee that the cancellation
+     * has happened or completed before this method returns.
+     * @param t reason for cancellation; typically a {@link FlowInterruptedException}
+     * @return false if the task cannot be cancelled.
      */
     public boolean cancel(Throwable t) {
-        return cancel(new ExceptionCause(t));
+        if (Util.isOverridden(BodyExecution.class, getClass(), "cancel", CauseOfInterruption[].class)) {
+            return cancel(new ExceptionCause(t));
+        } else {
+            throw new AbstractMethodError("Override cancel(Throwable) from " + getClass());
+        }
     }
 
     private static final long serialVersionUID = 1L;

src/main/java/org/jenkinsci/plugins/workflow/steps/FlowInterruptedException.java

@@ -67,14 +67,11 @@ public final class FlowInterruptedException extends InterruptedException {
     private Boolean actualInterruption = true;
 
     /**
-     * Creates a new exception.
-     * @param result the desired result for the flow, typically {@link Result#ABORTED}
-     * @param causes any indications
+     * @deprecated use {@link #FlowInterruptedException(Result, boolean, CauseOfInterruption...)}
      */
+    @Deprecated
     public FlowInterruptedException(@NonNull Result result, @NonNull CauseOfInterruption... causes) {
-        this.result = result;
-        this.causes = Arrays.asList(causes);
-        this.actualInterruption = true;
+        this(result, true, causes);
     }
 
     /**

src/main/java/org/jenkinsci/plugins/workflow/steps/SynchronousStepExecution.java

@@ -51,6 +51,7 @@ public void stop(Throwable cause) throws Exception {
         Thread e = executing;   // capture
         if (e!=null) {
             if (e instanceof Executor) {
+                // TODO if cause instanceof FlowInterruptedException, unpack result & causes
                 ((Executor) e).interrupt(ABORTED, new ExceptionCause(cause));
             } else {
                 e.interrupt();