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

Persistence

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

Assocaited Views

config.jelly

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.

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

static class

ParameterDefinition.ParameterDescriptor

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

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.
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	getName()
String	getType()

Methods inherited from class java.lang.Object

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

Field Detail

LIST

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(String name)

ParameterDefinition

public ParameterDefinition(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
public String getName()

getDescription

@Exported
public String getDescription()

getDescriptor

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>

createValue

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

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

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. You can use its CLICommand.checkChannel() for interacting with the CLI JVM.

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.

Exception - 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

@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

all

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

Returns all the registered ParameterDefinition descriptors.