Class ParameterDefinition

  extended by hudson.model.ParameterDefinition
All Implemented Interfaces:
ExtensionPoint, Describable<ParameterDefinition>, Serializable
Direct Known Subclasses:
FileParameterDefinition, SimpleParameterDefinition

public abstract class ParameterDefinition
extends Object
implements Describable<ParameterDefinition>, ExtensionPoint, Serializable

Defines a parameter for a build.

In Hudson, 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 implmentation 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.


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

Assocaited Views


ParameterDefinition class uses config.jelly to provide contribute a form fragment in the job configuration screen. Values entered there is fed back to Descriptor.newInstance(StaplerRequest, JSONObject) to create ParameterDefinitions.


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
static class ParameterDefinition.ParameterDescriptor
Nested classes/interfaces inherited from interface hudson.ExtensionPoint
Field Summary
static DescriptorList<ParameterDefinition> LIST
          Deprecated. as of 1.286 Use all() for read access, and Extension for registration.
Constructor Summary
ParameterDefinition(String name)
ParameterDefinition(String name, String description)
Method Summary
static DescriptorExtensionList<ParameterDefinition,ParameterDefinition.ParameterDescriptor> all()
          Returns all the registered ParameterDefinition descriptors.
 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 o)
 ParameterValue getDefaultParameterValue()
          Returns default parameter value for this definition.
 String getDescription()
 ParameterDefinition.ParameterDescriptor getDescriptor()
          Gets the descriptor for this instance.
 String getName()
 String getType()
 int hashCode()
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail


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


public ParameterDefinition(String name)


public ParameterDefinition(String name,
                           String description)
Method Detail


public String getType()


public String getName()


public String getDescription()


public ParameterDefinition.ParameterDescriptor getDescriptor()
Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass()==b.getClass() then a.getDescriptor()==b.getDescriptor() must hold.

Specified by:
getDescriptor in interface Describable<ParameterDefinition>


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.


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.


public ParameterValue createValue(CLICommand command,
                                  String value)
                           throws IOException,
Create a parameter value from the string given in the CLI.

command - This is the command that got the parameter. You can use its for interacting with the CLI JVM.
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.
Exception - All the other exceptions cause the stack trace to be dumped, and then the command exits with an error code.


public ParameterValue getDefaultParameterValue()
Returns default parameter value for this definition.

default parameter value or null if no defaults are available


public static DescriptorExtensionList<ParameterDefinition,ParameterDefinition.ParameterDescriptor> all()
Returns all the registered ParameterDefinition descriptors.


public boolean equals(Object o)
equals in class Object


public int hashCode()
hashCode in class Object

Copyright © 2004-2013 Hudson. All Rights Reserved.