Package 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.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • 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()

    • setDescription

      @DataBoundSetter public void setDescription(@CheckForNull String description)
      Since:
      2.281

    • 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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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

    • all

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