/hudson-core/src/main/java/hudson/model/ParameterValue.java

  1/*
  2 * The MIT License
  3 * 
  4 * Copyright (c) 2004-2010, Sun Microsystems, Inc., Kohsuke Kawaguchi, Tom Huybrechts,
  5 *      Yahoo! Inc.
  6 * 
  7 * Permission is hereby granted, free of charge, to any person obtaining a copy
  8 * of this software and associated documentation files (the "Software"), to deal
  9 * in the Software without restriction, including without limitation the rights
 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 11 * copies of the Software, and to permit persons to whom the Software is
 12 * furnished to do so, subject to the following conditions:
 13 * 
 14 * The above copyright notice and this permission notice shall be included in
 15 * all copies or substantial portions of the Software.
 16 * 
 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 23 * THE SOFTWARE.
 24 */
 25package hudson.model;
 26
 27import hudson.EnvVars;
 28import hudson.Util;
 29import hudson.tasks.BuildWrapper;
 30import hudson.tasks.Builder;
 31import hudson.util.VariableResolver;
 32
 33import java.io.Serializable;
 34import java.util.Map;
 35
 36import org.kohsuke.stapler.export.Exported;
 37import org.kohsuke.stapler.export.ExportedBean;
 38
 39/**
 40 * A value for a parameter in a build.
 41 *
 42 * Created by {@link ParameterDefinition#createValue(org.kohsuke.stapler.StaplerRequest, net.sf.json.JSONObject)} for
 43 * a particular build (although this 'owner' build object is passed in for every method
 44 * call as a parameter so that the parameter won't have to persist it.)
 45 *
 46 * <h2>Persistence</h2>
 47 * <p>
 48 * Instances of {@link ParameterValue}s are persisted into build's <tt>build.xml</tt>
 49 * through XStream (via {@link ParametersAction}), so instances need to be persistable.
 50 *
 51 * <h2>Assocaited Views</h2>
 52 * <h4>value.jelly</h4>
 53 * The <tt>value.jelly</tt> view contributes a UI fragment to display the parameter
 54 * values used for a build.
 55 *
 56 * <h2>Notes</h2>
 57 * <ol>
 58 * <li>{@link ParameterValue} is used to record values of the past build, but
 59 *     {@link ParameterDefinition} used back then might be gone already, or represent
 60 *     a different parameter now. So don't try to use the name to infer
 61 *     {@link ParameterDefinition} is.
 62 * </ol>
 63 * @see ParameterDefinition
 64 */
 65@ExportedBean(defaultVisibility=3)
 66public abstract class ParameterValue implements Serializable {
 67    protected final String name;
 68
 69    private String description;
 70
 71    protected ParameterValue(String name, String description) {
 72        this.name = name;
 73        this.description = description;
 74    }
 75
 76    protected ParameterValue(String name) {
 77        this(name, null);
 78    }
 79
 80    public String getDescription() {
 81        return description;
 82    }
 83
 84    public void setDescription(String description) {
 85        this.description = description;
 86    }
 87
 88    /**
 89     * Name of the parameter.
 90     *
 91     * This uniquely distinguishes {@link ParameterValue} among other parameters
 92     * for the same build. This must be the same as {@link ParameterDefinition#getName()}.
 93     */
 94    @Exported
 95    public final String getName() {
 96        return name;
 97    }
 98
 99    /**
100     * Adds environmental variables for the builds to the given map.
101     *
102     * <p>
103     * This provides a means for a parameter to pass the parameter
104     * values to the build to be performed.
105     *
106     * <p>
107     * When this method is invoked, the map already contains the
108     * current "planned export" list. The implementation is
109     * expected to add more values to this map (or do nothing)
110     *
111     * <p>
112     * <strike>Environment variables should be by convention all upper case.
113     * (This is so that a Windows/Unix heterogeneous environment
114     * won't get inconsistent result depending on which platform to
115     * execute.)</strike> (see {@link EnvVars} why upper casing is a bad idea.)
116     *
117     * @param env
118     *      never null.
119     * @param build
120     *      The build for which this parameter is being used. Never null.
121     * @deprecated as of 1.344
122     *      Use {@link #buildEnvVars(AbstractBuild, EnvVars)} instead.
123     */
124    public void buildEnvVars(AbstractBuild<?,?> build, Map<String,String> env) {
125        if (env instanceof EnvVars && Util.isOverridden(ParameterValue.class,getClass(),"buildEnvVars", AbstractBuild.class,EnvVars.class))
126            // if the subtype already derives buildEnvVars(AbstractBuild,Map), then delegate to it
127            buildEnvVars(build,(EnvVars)env);
128
129        // otherwise no-op by default
130    }
131
132    /**
133     * Adds environmental variables for the builds to the given map.
134     *
135     * <p>
136     * This provides a means for a parameter to pass the parameter
137     * values to the build to be performed.
138     *
139     * <p>
140     * When this method is invoked, the map already contains the
141     * current "planned export" list. The implementation is
142     * expected to add more values to this map (or do nothing)
143     *
144     * @param env
145     *      never null.
146     * @param build
147     *      The build for which this parameter is being used. Never null.
148     */
149    public void buildEnvVars(AbstractBuild<?,?> build, EnvVars env) {
150        // for backward compatibility
151        buildEnvVars(build,(Map<String,String>)env);
152    }
153
154    /**
155     * Called at the beginning of a build (but after {@link hudson.scm.SCM} operations
156     * have taken place) to let a {@link ParameterValue} contributes a
157     * {@link BuildWrapper} to the build.
158     *
159     * <p>
160     * This provides a means for a parameter to perform more extensive
161     * set up / tear down during a build.
162     *
163     * @param build
164     *      The build for which this parameter is being used. Never null.
165     * @return
166     *      null if the parameter has no {@link BuildWrapper} to contribute to.
167     */
168    public BuildWrapper createBuildWrapper(AbstractBuild<?,?> build) {
169        return null;
170    }
171
172    /**
173     * Returns a {@link VariableResolver} so that other components like {@link Builder}s
174     * can perform variable substitution to reflect parameter values into the build process.
175     *
176     * <p.
177     * This is yet another means in which a {@link ParameterValue} can influence
178     * a build.
179     *
180     * @param build
181     *      The build for which this parameter is being used. Never null.
182     * @return
183     *      if the parameter value is not interested in participating to the
184     *      variable replacement process, return {@link VariableResolver#NONE}.
185     */
186    public VariableResolver<String> createVariableResolver(AbstractBuild<?,?> build) {
187        return VariableResolver.NONE;
188    }
189
190    /**
191     * Accessing {@link ParameterDefinition} is not a good idea.
192     *
193     * @deprecated since 2008-09-20.
194     *    parameter definition may change any time. So if you find yourself
195     *    in need of accessing the information from {@link ParameterDefinition},
196     *    instead copy them in {@link ParameterDefinition#createValue(org.kohsuke.stapler.StaplerRequest, net.sf.json.JSONObject)}
197     *    into {@link ParameterValue}.
198     */
199    public ParameterDefinition getDefinition() {
200        throw new UnsupportedOperationException();
201    }
202
203    @Override
204    public int hashCode() {
205        final int prime = 31;
206        int result = 1;
207        result = prime * result + ((name == null) ? 0 : name.hashCode());
208        return result;
209    }
210
211    @Override
212    public boolean equals(Object obj) {
213        if (this == obj)
214            return true;
215        if (obj == null)
216            return false;
217        if (getClass() != obj.getClass())
218            return false;
219        ParameterValue other = (ParameterValue) obj;
220        if (name == null) {
221            if (other.name != null)
222                return false;
223        } else if (!name.equals(other.name))
224            return false;
225        return true;
226    }
227
228    /**
229     * Computes a human-readable possible-localized one-line description of the parameter value.
230     *
231     * <P>
232     * This message is used as a tooltip to describe jobs in the queue. The text should be one line without
233     * new line. No HTML allowed (the caller will perform necessary HTML escapes, so any text can be returend.)
234     *
235     * @since 1.323
236     */
237    public String getShortDescription() {
238        return toString();
239    }
240
241    /**
242     * Returns whether the information contained in this ParameterValue is
243     * sensitive or security related. Used to determine whether the value
244     * provided by this object should be masked in output.
245     *
246     * <p>
247     * Subclasses can override this to control the returne value.
248     *
249     * @since 1.378
250     */
251    public boolean isSensitive() {
252        return false;
253}
254}