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

http://github.com/hudson/hudson · Java · 254 lines · 77 code · 20 blank · 157 comment · 15 complexity · 508fcf4696ed66efb03777a51510a1d5 MD5 · raw file

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