hudson.model

Class ParameterDefinition

java.lang.Object

hudson.model.ParameterDefinition

All Implemented Interfaces:

ExtensionPoint, Describable<ParameterDefinition>, Serializable

Direct Known Subclasses:

FileParameterDefinition, SimpleParameterDefinition

@ExportedBean(defaultVisibility=3)
public abstract class ParameterDefinition
extends Object
implements Describable<ParameterDefinition>, ExtensionPoint, Serializable

Defines a parameter for a build.

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 ParameterDefinitions 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 ParameterDefinitions), 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.

Persistence

Instances of ParameterDefinitions are persisted into job config.xml through XStream.

Associated Views

config.jelly

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

index.jelly

The 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 ParameterValues. TODO: what Jelly pages does this object need for rendering UI? TODO: ParameterValue needs to have some mechanism to expose values to the build

See Also:

StringParameterDefinition, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ParameterDefinition.ParameterDescriptor

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
static DescriptorList<ParameterDefinition>	LIST Deprecated. as of 1.286 Use all() for read access, and Extension for registration.

Constructor Summary

Constructors

Constructor and Description
ParameterDefinition(String name)
ParameterDefinition(String name, String description)

Method Summary

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.
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()
boolean	isValid(ParameterValue value) Checks whether a given value is valid for this definition.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LIST

@Deprecated
public static final DescriptorList<ParameterDefinition> LIST

Deprecated. as of 1.286 Use all() for read access, and Extension for registration.

A list of available parameter definition types

Constructor Detail

ParameterDefinition

public ParameterDefinition(@NonNull
                           String name)

ParameterDefinition

public ParameterDefinition(@NonNull
                           String name,
                           String description)

Method Detail

copyWithDefaultValue

public ParameterDefinition copyWithDefaultValue(ParameterValue defaultValue)

Create a new instance of this parameter definition and use the passed parameter value as the default value.

Since:

1.405

getType

@Exported
public String getType()

getName

@Exported
 @NonNull
public String getName()

getDescription

@Exported
 @CheckForNull
public String getDescription()

getFormattedDescription

@CheckForNull
public String getFormattedDescription()

return parameter description, applying the configured MarkupFormatter for jenkins instance.

Since:

1.521

getDescriptor

@NonNull
public ParameterDefinition.ParameterDescriptor getDescriptor()

Description copied from interface: Describable

Gets the descriptor for this instance.

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

Specified by:

getDescriptor in interface Describable<ParameterDefinition>

createValue

@CheckForNull
public abstract ParameterValue createValue(org.kohsuke.stapler.StaplerRequest req,
                                                         net.sf.json.JSONObject jo)

Create a parameter value from a form submission.

This method is invoked when the user fills in the parameter values in the HTML form and submits it to the server.

createValue

@CheckForNull
public abstract ParameterValue createValue(org.kohsuke.stapler.StaplerRequest req)

Create a parameter value from a GET with query string. If no value is available in the request, it returns a default value if possible, or null.

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.

Throws:

IllegalStateException - If the parameter is deemed required but was missing in the submission.

createValue

@CheckForNull
public ParameterValue createValue(CLICommand command,
                                                String value)
                                         throws IOException,
                                                InterruptedException

Create a parameter value from the string given in the CLI.

Parameters:

command - This is the command that got the parameter.

Throws:

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

Since:

1.334

getDefaultParameterValue

@CheckForNull
 @Exported
public ParameterValue getDefaultParameterValue()

Returns default parameter value for this definition.

Returns:

default parameter value or null if no defaults are available

Since:

1.253

isValid

public boolean isValid(ParameterValue value)

Checks whether a given value is valid for this definition.

Parameters:

value - The value to validate.

Returns:

True if the value is valid for this definition. False if it is invalid.

Since:

2.244

all

public static DescriptorExtensionList<ParameterDefinition,ParameterDefinition.ParameterDescriptor> all()

Returns all the registered ParameterDefinition descriptors.