hudson.model

Class ParameterValue

java.lang.Object

hudson.model.ParameterValue

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BooleanParameterValue, FileParameterValue, JobParameterValue, PasswordParameterValue, RunParameterValue, StringParameterValue

@ExportedBean(defaultVisibility=3)
public abstract class ParameterValue
extends Object
implements Serializable

A value for a parameter in a build. Created by ParameterDefinition.createValue(StaplerRequest, JSONObject) for a particular build (although this 'owner' build object is passed in for every method call as a parameter so that the parameter won't have to persist it.)

Persistence

Instances of ParameterValues are persisted into build's build.xml through XStream (via ParametersAction), so instances need to be persistable.

Associated Views

value.jelly

The value.jelly view contributes a UI fragment to display the parameter values used for a build.

Notes

1. ParameterValue is used to record values of the past build, but ParameterDefinition used back then might be gone already, or represent a different parameter now. So don't try to use the name to infer ParameterDefinition is.

See Also:

ParameterDefinition, ParametersAction, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected String	name

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ParameterValue(String name)
protected	ParameterValue(String name, String description)

Method Summary

Modifier and Type	Method and Description
void	buildEnvironment(Run<?,?> build, EnvVars env) Adds environmental variables for the builds to the given map.
void	buildEnvVars(AbstractBuild<?,?> build, EnvVars env) Deprecated. Use buildEnvironment(Run, EnvVars) instead.
void	buildEnvVars(AbstractBuild<?,?> build, Map<String,String> env) Deprecated. as of 1.344 Use buildEnvironment(Run, EnvVars) instead.
BuildWrapper	createBuildWrapper(AbstractBuild<?,?> build) Called at the beginning of a build (but after SCM operations have taken place) to let a ParameterValue contributes a BuildWrapper to the build.
VariableResolver<String>	createVariableResolver(AbstractBuild<?,?> build) Returns a VariableResolver so that other components like Builders can perform variable substitution to reflect parameter values into the build process.
boolean	equals(Object obj)
Label	getAssignedLabel(SubTask task) Controls where the build (that this parameter is submitted to) will happen.
ParameterDefinition	getDefinition() Deprecated. since 2008-09-20. parameter definition may change any time. So if you find yourself in need of accessing the information from ParameterDefinition, instead copy them in ParameterDefinition.createValue(StaplerRequest, JSONObject) into ParameterValue.
String	getDescription()
String	getFormattedDescription()
String	getName() Name of the parameter.
String	getShortDescription() Computes a human-readable possible-localized one-line description of the parameter value.
Object	getValue() Returns the most natural Java object that represents the actual value, like boolean, string, etc.
int	hashCode()
boolean	isSensitive() Returns whether the information contained in this ParameterValue is sensitive or security related.
void	setDescription(String description)

Methods inherited from class java.lang.Object

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

Field Detail

name

protected final String name

Constructor Detail

ParameterValue

protected ParameterValue(String name,
                         String description)

ParameterValue

protected ParameterValue(String name)

Method Detail

getDescription

public String getDescription()

setDescription

public void setDescription(String description)

getFormattedDescription

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
public String getFormattedDescription()

getName

@Exported
public final String getName()

Name of the parameter. This uniquely distinguishes ParameterValue among other parameters for the same build. This must be the same as ParameterDefinition.getName().

buildEnvVars

@Deprecated
public void buildEnvVars(AbstractBuild<?,?> build,
                                     Map<String,String> env)

Deprecated. as of 1.344 Use buildEnvironment(Run, EnvVars) instead.

Adds environmental variables for the builds to the given map.

This provides a means for a parameter to pass the parameter values to the build to be performed.

When this method is invoked, the map already contains the current "planned export" list. The implementation is expected to add more values to this map (or do nothing)

Formerly, environment variables would be by convention all upper case. (This is so that a Windows/Unix heterogeneous environment won't get inconsistent result depending on which platform to execute.) But now see EnvVars why upper casing is a bad idea.

Parameters:

env - never null.

build - The build for which this parameter is being used. Never null.

buildEnvVars

@Deprecated
public void buildEnvVars(AbstractBuild<?,?> build,
                                     EnvVars env)

Deprecated. Use buildEnvironment(Run, EnvVars) instead.

buildEnvironment

public void buildEnvironment(Run<?,?> build,
                             EnvVars env)

Adds environmental variables for the builds to the given map.

This provides a means for a parameter to pass the parameter values to the build to be performed.

When this method is invoked, the map already contains the current "planned export" list. The implementation is expected to add more values to this map (or do nothing)

Parameters:

env - never null.

build - The build for which this parameter is being used. Never null.

Since:

1.556

createBuildWrapper

public BuildWrapper createBuildWrapper(AbstractBuild<?,?> build)

Called at the beginning of a build (but after SCM operations have taken place) to let a ParameterValue contributes a BuildWrapper to the build.

This provides a means for a parameter to perform more extensive set up / tear down during a build.

Parameters:

build - The build for which this parameter is being used. Never null.

Returns:

null if the parameter has no BuildWrapper to contribute to.

createVariableResolver

public VariableResolver<String> createVariableResolver(AbstractBuild<?,?> build)

Returns a VariableResolver so that other components like Builders can perform variable substitution to reflect parameter values into the build process.

This is yet another means in which a ParameterValue can influence a build.

Parameters:

build - The build for which this parameter is being used. Never null.

Returns:

if the parameter value is not interested in participating to the variable replacement process, return VariableResolver.NONE.

getDefinition

@Deprecated
public ParameterDefinition getDefinition()

Deprecated. since 2008-09-20. parameter definition may change any time. So if you find yourself in need of accessing the information from ParameterDefinition, instead copy them in ParameterDefinition.createValue(StaplerRequest, JSONObject) into ParameterValue.

Accessing ParameterDefinition is not a good idea.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

getShortDescription

public String getShortDescription()

Computes a human-readable possible-localized one-line description of the parameter value.

This message is used as a tooltip to describe jobs in the queue. The text should be one line without new line. No HTML allowed (the caller will perform necessary HTML escapes, so any text can be returned.)

Since:

1.323

isSensitive

public boolean isSensitive()

Returns whether the information contained in this ParameterValue is sensitive or security related. Used to determine whether the value provided by this object should be masked in output.

Subclasses can override this to control the return value.

Since:

1.378

getValue

@CheckForNull
public Object getValue()

Returns the most natural Java object that represents the actual value, like boolean, string, etc.

Returns:

if there is no natural value for this parameter type, this may be used; null may be used when the value is normally defined but missing in this case for various reasons

Since:

1.568

getAssignedLabel

public Label getAssignedLabel(SubTask task)

Controls where the build (that this parameter is submitted to) will happen.

Returns:

null to run the build where it normally runs. If non-null, this will override AbstractProject.getAssignedLabel(). If a build is submitted with multiple parameters, the first one that returns non-null from this method will win, and all others won't be consulted.

Since:

1.414