File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\model\ParameterValue.java.html

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 */
25 package hudson.model;
26
27 import hudson.EnvVars;
28 import hudson.Util;
29 import hudson.model.queue.SubTask;
30 import hudson.scm.SCM;
31 import hudson.tasks.BuildWrapper;
32 import hudson.tasks.Builder;
33 import hudson.util.VariableResolver;
34
35 import java.io.Serializable;
36 import java.util.Map;
37
38 import net.sf.json.JSONObject;
39
40 import org.kohsuke.stapler.StaplerRequest;
41 import org.kohsuke.stapler.export.Exported;
42 import org.kohsuke.stapler.export.ExportedBean;
43
44 /**
45 * A value for a parameter in a build.
46 *
47 * Created by {@link ParameterDefinition#createValue(StaplerRequest, JSONObject)} for
48 * a particular build (although this 'owner' build object is passed in for every method
49 * call as a parameter so that the parameter won't have to persist it.)
50 *
51 * <h2>Persistence</h2>
52 * <p>
53 * Instances of {@link ParameterValue}s are persisted into build's <tt>build.xml</tt>
54 * through XStream (via {@link ParametersAction}), so instances need to be persistable.
55 *
56 * <h2>Associated Views</h2>
57 * <h4>value.jelly</h4>
58 * The <tt>value.jelly</tt> view contributes a UI fragment to display the parameter
59 * values used for a build.
60 *
61 * <h2>Notes</h2>
62 * <ol>
63 * <li>{@link ParameterValue} is used to record values of the past build, but
64 * {@link ParameterDefinition} used back then might be gone already, or represent
65 * a different parameter now. So don't try to use the name to infer
66 * {@link ParameterDefinition} is.
67 * </ol>
68 * @see ParameterDefinition
69 * @see ParametersAction
70 */
71 @ExportedBean(defaultVisibility=3)
72 public abstract class ParameterValue implements Serializable {
73 protected final String name;
74
75 private String description;
76
77 protected ParameterValue(String name, String description) {
78 this.name = name;
79 this.description = description;
80 }
81
82 protected ParameterValue(String name) {
83 this(name, null);
84 }
85
86 public String getDescription() {
87 return description;
88 }
89
90 public void setDescription(String description) {
91 this.description = description;
92 }
93
94 /**
95 * Name of the parameter.
96 *
97 * This uniquely distinguishes {@link ParameterValue} among other parameters
98 * for the same build. This must be the same as {@link ParameterDefinition#getName()}.
99 */
100 @Exported
101 public final String getName() {
102 return name;
103 }
104
105 /**
106 * Adds environmental variables for the builds to the given map.
107 *
108 * <p>
109 * This provides a means for a parameter to pass the parameter
110 * values to the build to be performed.
111 *
112 * <p>
113 * When this method is invoked, the map already contains the
114 * current "planned export" list. The implementation is
115 * expected to add more values to this map (or do nothing)
116 *
117 * <p>
118 * <strike>Environment variables should be by convention all upper case.
119 * (This is so that a Windows/Unix heterogeneous environment
120 * won't get inconsistent result depending on which platform to
121 * execute.)</strike> (see {@link EnvVars} why upper casing is a bad idea.)
122 *
123 * @param env
124 * never null.
125 * @param build
126 * The build for which this parameter is being used. Never null.
127 * @deprecated as of 1.344
128 * Use {@link #buildEnvVars(AbstractBuild, EnvVars)} instead.
129 */
130 public void buildEnvVars(AbstractBuild<?,?> build, Map<String,String> env) {
131 if (env instanceof EnvVars && Util.isOverridden(ParameterValue.class,getClass(),"buildEnvVars", AbstractBuild.class,EnvVars.class))
132 // if the subtype already derives buildEnvVars(AbstractBuild,Map), then delegate to it
133 buildEnvVars(build,(EnvVars)env);
134
135 // otherwise no-op by default
136 }
137
138 /**
139 * Adds environmental variables for the builds to the given map.
140 *
141 * <p>
142 * This provides a means for a parameter to pass the parameter
143 * values to the build to be performed.
144 *
145 * <p>
146 * When this method is invoked, the map already contains the
147 * current "planned export" list. The implementation is
148 * expected to add more values to this map (or do nothing)
149 *
150 * @param env
151 * never null.
152 * @param build
153 * The build for which this parameter is being used. Never null.
154 */
155 public void buildEnvVars(AbstractBuild<?,?> build, EnvVars env) {
156 // for backward compatibility
157 buildEnvVars(build,(Map<String,String>)env);
158 }
159
160 /**
161 * Called at the beginning of a build (but after {@link SCM} operations
162 * have taken place) to let a {@link ParameterValue} contributes a
163 * {@link BuildWrapper} to the build.
164 *
165 * <p>
166 * This provides a means for a parameter to perform more extensive
167 * set up / tear down during a build.
168 *
169 * @param build
170 * The build for which this parameter is being used. Never null.
171 * @return
172 * null if the parameter has no {@link BuildWrapper} to contribute to.
173 */
174 public BuildWrapper createBuildWrapper(AbstractBuild<?,?> build) {
175 return null;
176 }
177
178 /**
179 * Returns a {@link VariableResolver} so that other components like {@link Builder}s
180 * can perform variable substitution to reflect parameter values into the build process.
181 *
182 * <p.
183 * This is yet another means in which a {@link ParameterValue} can influence
184 * a build.
185 *
186 * @param build
187 * The build for which this parameter is being used. Never null.
188 * @return
189 * if the parameter value is not interested in participating to the
190 * variable replacement process, return {@link VariableResolver#NONE}.
191 */
192 public VariableResolver<String> createVariableResolver(AbstractBuild<?,?> build) {
193 return VariableResolver.NONE;
194 }
195
196 /**
197 * Accessing {@link ParameterDefinition} is not a good idea.
198 *
199 * @deprecated since 2008-09-20.
200 * parameter definition may change any time. So if you find yourself
201 * in need of accessing the information from {@link ParameterDefinition},
202 * instead copy them in {@link ParameterDefinition#createValue(StaplerRequest, JSONObject)}
203 * into {@link ParameterValue}.
204 */
205 public ParameterDefinition getDefinition() {
206 throw new UnsupportedOperationException();
207 }
208
209 @Override
210 public int hashCode() {
211 final int prime = 31;
212 int result = 1;
213 result = prime * result + ((name == null) ? 0 : name.hashCode());
214 return result;
215 }
216
217 @Override
218 public boolean equals(Object obj) {
219 if (this == obj)
220 return true;
221 if (obj == null)
222 return false;
223 if (getClass() != obj.getClass())
224 return false;
225 ParameterValue other = (ParameterValue) obj;
226 if (name == null) {
227 if (other.name != null)
228 return false;
229 } else if (!name.equals(other.name))
230 return false;
231 return true;
232 }
233
234 /**
235 * Computes a human-readable possible-localized one-line description of the parameter value.
236 *
237 * <P>
238 * This message is used as a tooltip to describe jobs in the queue. The text should be one line without
239 * new line. No HTML allowed (the caller will perform necessary HTML escapes, so any text can be returend.)
240 *
241 * @since 1.323
242 */
243 public String getShortDescription() {
244 return toString();
245 }
246
247 /**
248 * Returns whether the information contained in this ParameterValue is
249 * sensitive or security related. Used to determine whether the value
250 * provided by this object should be masked in output.
251 *
252 * <p>
253 * Subclasses can override this to control the return value.
254 *
255 * @since 1.378
256 */
257 public boolean isSensitive() {
258 return false;
259 }
260
261 /**
262 * Controls where the build (that this parameter is submitted to) will happen.
263 *
264 * @return
265 * null to run the build where it normally runs. If non-null, this will
266 * override {@link AbstractProject#getAssignedLabel()}. If a build is
267 * submitted with multiple parameters, the first one that returns non-null
268 * from this method will win, and all others won't be consulted.
269 *
270 *
271 * @since 1.414
272 */
273 public Label getAssignedLabel(SubTask task) {
274 return null;
275 }
276 }
277