Class StepDescriptor
- java.lang.Object
-
- hudson.model.Descriptor<Step>
-
- org.jenkinsci.plugins.workflow.steps.StepDescriptor
-
- Direct Known Subclasses:
AbstractStepDescriptorImpl
public abstract class StepDescriptor extends Descriptor<Step>
- Author:
- Kohsuke Kawaguchi, Jesse Glick
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class hudson.model.Descriptor
Descriptor.FormException, Descriptor.PropertyType, Descriptor.Self
-
-
Field Summary
-
Fields inherited from class hudson.model.Descriptor
clazz
-
-
Constructor Summary
Constructors Constructor Description StepDescriptor()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static ExtensionList<StepDescriptor>
all()
static Iterable<StepDescriptor>
allMeta()
Convenience method to iterate all meta step descriptors.String
argumentsToString(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.static StepDescriptor
byFunctionName(String name)
Obtains aStepDescriptor
by its function name, or null if not found.void
checkContextAvailability(StepContext c)
Makes sure that the givenStepContext
has all the context parameters this descriptor wants to see, and if not, throwMissingContextVariableException
indicating which variable is missing.Map<String,Object>
defineArguments(Step step)
Deprecated.abstract String
getFunctionName()
Return a short string that is a valid identifier for programming languages.Class<?>
getMetaStepArgumentType()
For a meta step, return the type that this meta step handles.Set<? extends Class<?>>
getProvidedContext()
Returns the contextStep
adds/sets/modifies when executing a body.abstract Set<? extends Class<?>>
getRequiredContext()
Enumerates any kinds of context theStepExecution
will treat as mandatory.boolean
isAdvanced()
For UI presentation purposes, allows a plugin to mark a step as deprecated or advanced.boolean
isMetaStep()
Some steps, such asCoreStep
orGenericSCMStep
can take arbitraryDescribable
s of a certain type and execute it as a step.static List<StepDescriptor>
metaStepsOf(String symbol)
Given a symbol, attempt to find all the meta-steps that can consume this symbol.Step
newInstance(Map<String,Object> arguments)
Deprecated.instead useCustomDescribableModel
boolean
takesImplicitBlockArgument()
Return true if this step can accept an implicit block argument.org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable
uninstantiate(Step step)
Deprecated.instead useCustomDescribableModel
-
Methods inherited from class hudson.model.Descriptor
addHelpFileRedirect, calcAutoCompleteSettings, calcFillSettings, configure, configure, doHelp, find, find, findByDescribableClassName, findById, getCategory, getCheckMethod, getCheckUrl, getConfigFile, getConfigPage, getCurrentDescriptorByNameUrl, getDescriptorFullUrl, getDescriptorUrl, getDisplayName, getGlobalConfigPage, getGlobalPropertyType, getHelpFile, getHelpFile, getHelpFile, getId, getJsonSafeClassName, getKlass, getPlugin, getPossibleViewNames, getPropertyType, getPropertyType, getPropertyTypeOrDie, getRequiredGlobalConfigPagePermission, getT, getViewPage, isInstance, isSubTypeOf, load, newInstance, newInstance, newInstancesFromHeteroList, newInstancesFromHeteroList, save, self, toArray, toList, toMap
-
-
-
-
Method Detail
-
getRequiredContext
public abstract Set<? extends Class<?>> getRequiredContext()
Enumerates any kinds of context theStepExecution
will treat as mandatory. WhenStepContext.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 aLauncher
may only be run inside anode {…}
block.- Returns:
- a set of context types like
TaskListener
orRun
orFilePath
-
getProvidedContext
public Set<? extends Class<?>> getProvidedContext()
Returns the contextStep
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.
-
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.)
-
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 asCoreStep
orGenericSCMStep
can take arbitraryDescribable
s of a certain type and execute it as a step. Such a step should return true from this method so thatDescribable
s 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
Describable
s 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 aDescribable
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 useCustomDescribableModel
Used when aStep
is instantiated programmatically. The default implementation just usesDescribableModel.instantiate(java.util.Map<java.lang.String, ?>)
.- Parameters:
arguments
- Named arguments and values, à la Ant task or Maven mojos. Generally should follow the semantics ofDescribableModel.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.Determine which arguments went into the configuration of a step configured through a form submission.- Parameters:
step
- a fully-configured step (assignable toDescriptor.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 useCustomDescribableModel
Determine which arguments went into the configuration of a step configured through a form submission.- Parameters:
step
- a fully-configured step (assignable toDescriptor.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 givenStepContext
has all the context parameters this descriptor wants to see, and if not, throwMissingContextVariableException
indicating which variable is missing.
-
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 aStepDescriptor
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. ComplementsDescriptor.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 fromdefineArguments(Step)
or supplied tonewInstance(Map)
- Returns:
- Formatted string, before escaping, or null if can't be converted easily to a String.
-
-