[JENKINS-29922] mark meta step

pom.xml

@@ -80,7 +80,7 @@
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>
             <artifactId>structs</artifactId>
-            <version>1.1</version>
+            <version>1.3-SNAPSHOT</version>
         </dependency>
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>

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

@@ -24,15 +24,26 @@
 
 package org.jenkinsci.plugins.workflow.steps;
 
+import com.google.common.base.Predicate;
+import com.google.common.collect.Iterables;
 import hudson.ExtensionList;
+import hudson.Util;
+import hudson.model.Describable;
 import hudson.model.Descriptor;
 
 import java.io.IOException;
 import java.util.Collections;
 import java.util.Map;
 import java.util.Set;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 import org.jenkinsci.plugins.structs.describable.DescribableModel;
+import org.jenkinsci.plugins.structs.describable.DescribableParameter;
+import org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable;
+import org.kohsuke.stapler.DataBoundConstructor;
+
+import javax.annotation.Nullable;
 
 /**
  * @author Kohsuke Kawaguchi
@@ -92,6 +103,79 @@ public boolean isAdvanced() {
         return false;
     }
 
+    /**
+     * Some steps, such as {@code CoreStep} or {@code GenericSCMStep} can take
+     * arbitrary {@link Describable}s of a certain type and execute it as a step.
+     * Such a step should return true from this method so that {@link Describable}s that
+     * it supports can be directly written as a step as a short-hand.
+     *
+     * <p>
+     * Meta-step works as an invisible adapter that creates an illusion that {@link Describable}s are
+     * steps.
+     *
+     * <p>
+     * For example, in Jenkins Pipeline, if there is a meta step that can handle a {@link Describable},
+     * and it has a symbol, it allows the following short-hand:
+     *
+     * <pre>
+     * public class Xyz extends Foo {
+     *     &#64;DataBoundConstructor
+     *     public Xyz(String value) { ... }
+     *
+     *     &#64;Extension &#64;Symbol("xyz")
+     *     public static class DescriptorImpl extends FooDescriptor { ... }
+     * }
+     *
+     * public class MetaStepForFoo extends AbstractStepImpl {
+     *     &#64;DataBoundConstructor
+     *     public MetaStepForFoo(Foo delegate) {
+     *         ...
+     *     }
+     *
+     *     ...
+     *     &#64;Extension
+     *     public static class DescriptorImpl extends AbstractStepDescriptorImpl {
+     *         &#64;Override
+     *         public String getFunctionName() {
+     *             return "metaStepForFoo";
+     *         }
+     *     }
+     * }
+     *
+     * // this is the short-hand that users will use
+     * xyz('hello')
+     * // but this is how it actually gets executed
+     * metaStepForFoo(xyz('hello'))
+     * </pre>
+     *
+     * <p>
+     * Meta-step must have a {@link DataBoundConstructor} whose first argument represents a
+     * {@link Describable} that it handles.
+     */
+    public boolean isMetaStep() {
+        return false;
+    }
+
+    /**
+     * For a {@linkplain #isMetaStep() meta step}, return the type that this meta step handles.
+     * Otherwise null.
+     */
+    // not @CheckForNull because often the caller is using allMeta()
+    public final Class<?> getMetaStepArgumentType() {
+        if (!isMetaStep())  return null;
+
+        DescribableModel<?> m = new DescribableModel(clazz);
+        DescribableParameter p = m.getFirstRequiredParameter();
+        if (p==null) {
+            LOGGER.log(Level.WARNING, getClass()+" claims to be a meta-step but it has no parameter in @DataBoundConstructor");
+            // don't punish users for a mistake by a plugin developer. return null instead of throwing an error.
+            // returning a type that doesn't match anything normally prevents this broken StepDescriptor from getting used.
+            return Void.class;
+        }
+
+        return p.getErasedType();
+    }
+
     /**
      * Used when a {@link Step} is instantiated programmatically.
      * The default implementation just uses {@link DescribableModel#instantiate}.
@@ -109,9 +193,33 @@ public Step newInstance(Map<String,Object> arguments) throws Exception {
      * @param step a fully-configured step (assignable to {@link #clazz})
      * @return arguments that could be passed to {@link #newInstance} to create a similar step instance
      * @throws UnsupportedOperationException if this descriptor lacks the ability to do such a calculation
+     * @deprecated
+     *      Use {@link #uninstantiate(Step)}
      */
     public Map<String,Object> defineArguments(Step step) throws UnsupportedOperationException {
-        return DescribableModel.uninstantiate_(step);
+        if (Util.isOverridden(StepDescriptor.class, getClass(), "uninstantiate", Step.class)) {
+            // if the subtype has defined the uninstantiate() method, delegate to that
+            return uninstantiate(step).toMap();
+        } else {
+            // otherwise assume legacy usage
+            return DescribableModel.uninstantiate_(step);
+        }
+    }
+
+    /**
+     * Determine which arguments went into the configuration of a step configured through a form submission.
+     * @param step a fully-configured step (assignable to {@link #clazz})
+     * @return arguments that could be passed to {@link #newInstance} to create a similar step instance
+     * @throws UnsupportedOperationException if this descriptor lacks the ability to do such a calculation
+     */
+    public UninstantiatedDescribable uninstantiate(Step step) throws UnsupportedOperationException {
+        if (Util.isOverridden(StepDescriptor.class, getClass(), "uninstantiate", Step.class)) {
+            // newer clients are called older implementations
+            return new UninstantiatedDescribable(defineArguments(step));
+        } else {
+            // the default behaviour in the absence of any overrides
+            return DescribableModel.uninstantiate2_(step);
+        }
     }
 
 
@@ -131,4 +239,18 @@ public final void checkContextAvailability(StepContext c) throws MissingContextV
     public static ExtensionList<StepDescriptor> all() {
         return ExtensionList.lookup(StepDescriptor.class);
     }
+
+    /**
+     * Convenience method to iterate all meta step descriptors.
+     */
+    public static Iterable<StepDescriptor> allMeta() {
+        return Iterables.filter(all(), new Predicate<StepDescriptor>() {
+            @Override
+            public boolean apply(@Nullable StepDescriptor i) {
+                return i!=null && i.isMetaStep();
+            }
+        });
+    }
+
+    private static final Logger LOGGER = Logger.getLogger(StepDescriptor.class.getName());
 }