Package org.jenkinsci.plugins.workflow.steps

Class StepDescriptor

    • Constructor Detail

      • StepDescriptor

        public StepDescriptor()

    • Method Detail

      • 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:
        MissingContextVariableException

      • 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.

      • 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

      • allMeta

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

      • 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.