@ExportedBean(defaultVisibility=3) public abstract class ParameterDefinition extends Object implements Describable<ParameterDefinition>, ExtensionPoint, Serializable
In Jenkins, a user can configure a job to require parameters for a build. For example, imagine a test job that takes the bits to be tested as a parameter.
The actual meaning and the purpose of parameters are entirely up to users, so
what the concrete parameter implementation is pluggable. Write subclasses
in a plugin and put Extension
on the descriptor to register them.
Three classes are used to model build parameters. First is the
ParameterDefinition.ParameterDescriptor
, which tells Hudson what kind of implementations are
available. From Descriptor.newInstance(StaplerRequest, JSONObject)
,
Hudson creates ParameterDefinition
s based on the job configuration.
For example, if the user defines two string parameters "database-type" and
"appserver-type", we'll get two StringParameterDefinition
instances
with their respective names.
When a job is configured with ParameterDefinition
(or more precisely,
ParametersDefinitionProperty
, which in turns retains ParameterDefinition
s),
user would have to enter the values for the defined build parameters.
The createValue(StaplerRequest, JSONObject)
method is used to convert this
form submission into ParameterValue
objects, which are then accessible
during a build.
Instances of ParameterDefinition
s are persisted into job config.xml
through XStream.
ParameterDefinition
class uses config.jelly
to contribute a form
fragment in the job configuration screen. Values entered there are fed back to
Descriptor.newInstance(StaplerRequest, JSONObject)
to create ParameterDefinition
s.
index.jelly
view contributes a form fragment in the page where the user
enters actual values of parameters for a build. The result of this form submission
is then fed to createValue(StaplerRequest, JSONObject)
to
create ParameterValue
s.
TODO: what Jelly pages does this object need for rendering UI?
TODO: ParameterValue
needs to have some mechanism to expose values to the buildStringParameterDefinition
,
Serialized FormModifier and Type | Class and Description |
---|---|
static class |
ParameterDefinition.ParameterDescriptor |
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
static DescriptorList<ParameterDefinition> |
LIST
|
Constructor and Description |
---|
ParameterDefinition(String name) |
ParameterDefinition(String name,
String description) |
Modifier and Type | Method and Description |
---|---|
static DescriptorExtensionList<ParameterDefinition,ParameterDefinition.ParameterDescriptor> |
all()
Returns all the registered
ParameterDefinition descriptors. |
ParameterDefinition |
copyWithDefaultValue(ParameterValue defaultValue)
Create a new instance of this parameter definition and use the passed
parameter value as the default value.
|
ParameterValue |
createValue(CLICommand command,
String value)
Create a parameter value from the string given in the CLI.
|
abstract ParameterValue |
createValue(org.kohsuke.stapler.StaplerRequest req)
Create a parameter value from a GET with query string.
|
abstract ParameterValue |
createValue(org.kohsuke.stapler.StaplerRequest req,
net.sf.json.JSONObject jo)
Create a parameter value from a form submission.
|
boolean |
equals(Object obj) |
ParameterValue |
getDefaultParameterValue()
Returns default parameter value for this definition.
|
String |
getDescription() |
ParameterDefinition.ParameterDescriptor |
getDescriptor()
Gets the descriptor for this instance.
|
String |
getFormattedDescription()
return parameter description, applying the configured MarkupFormatter for jenkins instance.
|
String |
getName() |
String |
getType() |
int |
hashCode() |
boolean |
isValid(ParameterValue value)
Checks whether a given value is valid for this definition.
|
@Deprecated public static final DescriptorList<ParameterDefinition> LIST
public ParameterDefinition(@NonNull String name)
public ParameterDefinition copyWithDefaultValue(ParameterValue defaultValue)
@Exported public String getType()
@Exported @NonNull public String getName()
@Exported @CheckForNull public String getDescription()
@CheckForNull public String getFormattedDescription()
@NonNull public ParameterDefinition.ParameterDescriptor getDescriptor()
Describable
Descriptor
is a singleton for every concrete Describable
implementation, so if a.getClass() == b.getClass()
then by default
a.getDescriptor() == b.getDescriptor()
as well.
(In rare cases a single implementation class may be used for instances with distinct descriptors.)
getDescriptor
in interface Describable<ParameterDefinition>
@CheckForNull public abstract ParameterValue createValue(org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject jo)
This method is invoked when the user fills in the parameter values in the HTML form and submits it to the server.
@CheckForNull public abstract ParameterValue createValue(org.kohsuke.stapler.StaplerRequest req)
Unlike createValue(StaplerRequest, JSONObject)
, this method is intended to support
the programmatic POST-ing of the build URL. This form is less expressive (as it doesn't support
the tree form), but it's more scriptable.
If a ParameterDefinition
can't really support this mode of creating a value,
you may just always return null.
IllegalStateException
- If the parameter is deemed required but was missing in the submission.@CheckForNull public ParameterValue createValue(CLICommand command, String value) throws IOException, InterruptedException
command
- This is the command that got the parameter.AbortException
- If the CLI processing should be aborted. Hudson will report the error message
without stack trace, and then exits this command. Useful for graceful termination.RuntimeException
- All the other exceptions cause the stack trace to be dumped, and then
the command exits with an error code.IOException
InterruptedException
@CheckForNull @Exported public ParameterValue getDefaultParameterValue()
public boolean isValid(ParameterValue value)
value
- The value to validate.public static DescriptorExtensionList<ParameterDefinition,ParameterDefinition.ParameterDescriptor> all()
ParameterDefinition
descriptors.Copyright © 2004–2021. All rights reserved.