Package org.jenkinsci.plugins.workflow.steps

Class StepDescriptor

java.lang.Object
hudson.model.Descriptor<Step>
org.jenkinsci.plugins.workflow.steps.StepDescriptor
All Implemented Interfaces:
Saveable, Loadable, OnMaster
Direct Known Subclasses:
AbstractStepDescriptorImpl
public abstract class StepDescriptor extends Descriptor<Step>
Author:
Kohsuke Kawaguchi, Jesse Glick

  • Constructor Details

    • StepDescriptor

      public StepDescriptor()

  • Method Details

    • getRequiredContext

      public abstract Set<? extends Class<?>> getRequiredContext()
      Enumerates any kinds of context the StepExecution will treat as mandatory. When StepContext.get(java.lang.Class<T>) is called, the return value may be null in general; if your step cannot trivially handle a null value of a given kind, list that type here. The Pipeline execution engine will then signal a user error before even starting your step if called in an inappropriate context. For example, a step requesting a Launcher may only be run inside a node {…} block.
      Returns:
      a set of context types like TaskListener or Run or FilePath

    • getProvidedContext

      public Set<? extends Class<?>> getProvidedContext()
      Returns the context Step adds/sets/modifies when executing a body.

      This is used to diagnose a "missing context" problem by suggesting what wrapper steps were likely missing. Steps that does not take a body block must return the empty set as it has nothing to contribute to the context.

      This set and getRequiredContext() can be compared to determine context variables that are newly added (as opposed to get merely decorated.)

      See Also:

    • getFunctionName

      public abstract String getFunctionName()
      Return a short string that is a valid identifier for programming languages. Follow the pattern [a-z][A-Za-z0-9_]*. Step will be referenced by this name when used in a programming language.

    • takesImplicitBlockArgument

      public boolean takesImplicitBlockArgument()
      Return true if this step can accept an implicit block argument. (If it can, but it is called without a block, StepContext.hasBody() will be false.)
      See Also:

    • isAdvanced

      public boolean isAdvanced()
      For UI presentation purposes, allows a plugin to mark a step as deprecated or advanced.
      Returns:
      true to exclude from main list of steps

    • isMetaStep

      public boolean isMetaStep()
      Some steps, such as CoreStep or GenericSCMStep can take arbitrary Describables of a certain type and execute it as a step. Such a step should return true from this method so that Describables that it supports can be directly written as a step as a short-hand.

      Meta-step works as an invisible adapter that creates an illusion that Describables are steps.

      For example, in Jenkins Pipeline, if there is a meta step that can handle a Describable, and it has a symbol, it allows the following short-hand: 

       public class Xyz extends Foo {
     @DataBoundConstructor
     public Xyz(String value) { ... }

     @Extension @Symbol("xyz")
     public static class DescriptorImpl extends FooDescriptor { ... }
 }

 public class MetaStepForFoo extends AbstractStepImpl {
     @DataBoundConstructor
     public MetaStepForFoo(Foo delegate) {
         ...
     }

     ...
     @Extension
     public static class DescriptorImpl extends AbstractStepDescriptorImpl {
         @Override
         public String getFunctionName() {
             return "metaStepForFoo";
         }
         @Override
         public boolean isMetaStep() {
             return true;
         }
     }
 }

 // this is the short-hand that users will use
 xyz('hello')
 // but this is how it actually gets executed
 metaStepForFoo(xyz('hello'))

      Meta-step must have a DataBoundConstructor whose first argument represents a Describable that it handles.

    • getMetaStepArgumentType

      @Nullable public final Class<?> getMetaStepArgumentType()
      For a meta step, return the type that this meta step handles. Otherwise null.

    • newInstance

      @Deprecated public Step newInstance(Map<String,Object> arguments) throws Exception
      Deprecated.
      instead use CustomDescribableModel
      Used when a Step is instantiated programmatically. The default implementation just uses DescribableModel.instantiate(java.util.Map<java.lang.String, ?>).
      Parameters:
      arguments - Named arguments and values, à la Ant task or Maven mojos. Generally should follow the semantics of DescribableModel.instantiate(java.util.Map<java.lang.String, ?>).
      Returns:
      an instance of Descriptor.clazz
      Throws:
      Exception

    • defineArguments

      @Deprecated public Map<String,Object> defineArguments(Step step) throws UnsupportedOperationException
      Deprecated.
      Use uninstantiate(Step)
      Determine which arguments went into the configuration of a step configured through a form submission.
      Parameters:
      step - a fully-configured step (assignable to Descriptor.clazz)
      Returns:
      arguments that could be passed to newInstance(java.util.Map<java.lang.String, java.lang.Object>) to create a similar step instance
      Throws:
      UnsupportedOperationException - if this descriptor lacks the ability to do such a calculation

    • uninstantiate

      @Deprecated public org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable uninstantiate(Step step) throws UnsupportedOperationException
      Deprecated.
      instead use CustomDescribableModel
      Determine which arguments went into the configuration of a step configured through a form submission.
      Parameters:
      step - a fully-configured step (assignable to Descriptor.clazz)
      Returns:
      arguments that could be passed to newInstance(java.util.Map<java.lang.String, java.lang.Object>) to create a similar step instance
      Throws:
      UnsupportedOperationException - if this descriptor lacks the ability to do such a calculation

    • checkContextAvailability

      public final void checkContextAvailability(StepContext c) throws MissingContextVariableException, IOException, InterruptedException
      Makes sure that the given StepContext has all the context parameters this descriptor wants to see, and if not, throw MissingContextVariableException indicating which variable is missing.
      Throws:
      MissingContextVariableException
      IOException
      InterruptedException

    • all

      public static ExtensionList<StepDescriptor> all()

    • allMeta

      public static Iterable<StepDescriptor> allMeta()
      Convenience method to iterate all meta step descriptors.

    • byFunctionName

      @Nullable public static StepDescriptor byFunctionName(String name)
      Obtains a StepDescriptor by its function name, or null if not found.

    • metaStepsOf

      @NonNull public static List<StepDescriptor> metaStepsOf(String symbol)
      Given a symbol, attempt to find all the meta-steps that can consume this symbol. When the returned list is bigger than size 1, it means there's ambiguity in how to process it.

    • argumentsToString

      @CheckForNull public String argumentsToString(@NonNull Map<String,Object> namedArgs)
      Converts user-supplied step arguments to a string for eventual UI use -- override me to handle more than a single trivial argument. Complements Descriptor.getDisplayName() in cases where the step type is less meaningful than its arguments (scripts, for example). Note: this offers a raw value and does not perform escaping on its own.
      Parameters:
      namedArgs - List of parameter name-value pairs supplied to the step to instantiate it, as from defineArguments(Step) or supplied to newInstance(Map)
      Returns:
      Formatted string, before escaping, or null if can't be converted easily to a String.