Class StepDescriptor
- Direct Known Subclasses:
AbstractStepDescriptorImpl
- 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
-
Method Summary
Modifier and TypeMethodDescriptionstatic ExtensionList<StepDescriptor>
all()
static Iterable<StepDescriptor>
allMeta()
Convenience method to iterate all meta step descriptors.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.final void
Makes sure that the givenStepContext
has all the context parameters this descriptor wants to see, and if not, throwMissingContextVariableException
indicating which variable is missing.defineArguments
(Step step) Deprecated.abstract String
Return a short string that is a valid identifier for programming languages.final Class<?>
For a meta step, return the type that this meta step handles.Returns the contextStep
adds/sets/modifies when executing a body.Enumerates any kinds of context theStepExecution
will treat as mandatory.boolean
For UI presentation purposes, allows a plugin to mark a step as deprecated or advanced.boolean
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.newInstance
(Map<String, Object> arguments) Deprecated.instead useCustomDescribableModel
boolean
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, bindJSON, 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
-
Constructor Details
-
StepDescriptor
public StepDescriptor()
-
-
Method Details
-
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
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:
-
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
For a meta step, return the type that this meta step handles. Otherwise null. -
newInstance
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
-
allMeta
Convenience method to iterate all meta step descriptors. -
byFunctionName
Obtains aStepDescriptor
by its function name, or null if not found. -
metaStepsOf
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
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.
-
uninstantiate(Step)