hudson.model
Class ParameterDefinition

java.lang.Object
  extended by 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.
 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

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

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.


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


equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object


Copyright © 2004-2013 Hudson. All Rights Reserved.