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

http://github.com/hudson/hudson · Java · 253 lines · 91 code · 27 blank · 135 comment · 9 complexity · e75021eec056b716e09817881786fa4f MD5 · raw file

  1. /*
  2. * The MIT License
  3. *
  4. * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, Luca Domenico Milanesio, Tom Huybrechts
  5. *
  6. * Permission is hereby granted, free of charge, to any person obtaining a copy
  7. * of this software and associated documentation files (the "Software"), to deal
  8. * in the Software without restriction, including without limitation the rights
  9. * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10. * copies of the Software, and to permit persons to whom the Software is
  11. * furnished to do so, subject to the following conditions:
  12. *
  13. * The above copyright notice and this permission notice shall be included in
  14. * all copies or substantial portions of the Software.
  15. *
  16. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19. * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20. * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21. * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22. * THE SOFTWARE.
  23. */
  24. package hudson.model;
  25. import hudson.AbortException;
  26. import hudson.DescriptorExtensionList;
  27. import hudson.Extension;
  28. import hudson.ExtensionPoint;
  29. import hudson.cli.CLICommand;
  30. import hudson.util.DescriptorList;
  31. import java.io.IOException;
  32. import java.io.Serializable;
  33. import net.sf.json.JSONObject;
  34. import org.apache.commons.lang3.builder.HashCodeBuilder;
  35. import org.kohsuke.stapler.StaplerRequest;
  36. import org.kohsuke.stapler.export.Exported;
  37. import org.kohsuke.stapler.export.ExportedBean;
  38. /**
  39. * Defines a parameter for a build.
  40. *
  41. * <p>
  42. * In Hudson, a user can configure a job to require parameters for a build.
  43. * For example, imagine a test job that takes the bits to be tested as a parameter.
  44. *
  45. * <p>
  46. * The actual meaning and the purpose of parameters are entirely up to users, so
  47. * what the concrete parameter implmentation is pluggable. Write subclasses
  48. * in a plugin and put {@link Extension} on the descriptor to register them.
  49. *
  50. * <p>
  51. * Three classes are used to model build parameters. First is the
  52. * {@link ParameterDescriptor}, which tells Hudson what kind of implementations are
  53. * available. From {@link ParameterDescriptor#newInstance(StaplerRequest, JSONObject)},
  54. * Hudson creates {@link ParameterDefinition}s based on the job configuration.
  55. * For example, if the user defines two string parameters "database-type" and
  56. * "appserver-type", we'll get two {@link StringParameterDefinition} instances
  57. * with their respective names.
  58. *
  59. * <p>
  60. * When a job is configured with {@link ParameterDefinition} (or more precisely,
  61. * {@link ParametersDefinitionProperty}, which in turns retains {@link ParameterDefinition}s),
  62. * user would have to enter the values for the defined build parameters.
  63. * The {@link #createValue(StaplerRequest, JSONObject)} method is used to convert this
  64. * form submission into {@link ParameterValue} objects, which are then accessible
  65. * during a build.
  66. *
  67. *
  68. *
  69. * <h2>Persistence</h2>
  70. * <p>
  71. * Instances of {@link ParameterDefinition}s are persisted into job <tt>config.xml</tt>
  72. * through XStream.
  73. *
  74. *
  75. * <h2>Assocaited Views</h2>
  76. * <h4>config.jelly</h4>
  77. * <p>
  78. * {@link ParameterDefinition} class uses <tt>config.jelly</tt> to provide contribute a form
  79. * fragment in the job configuration screen. Values entered there is fed back to
  80. * {@link ParameterDescriptor#newInstance(StaplerRequest, JSONObject)} to create {@link ParameterDefinition}s.
  81. *
  82. * <h4>index.jelly</h4>
  83. * The <tt>index.jelly</tt> view contributes a form fragment in the page where the user
  84. * enters actual values of parameters for a build. The result of this form submission
  85. * is then fed to {@link ParameterDefinition#createValue(StaplerRequest, JSONObject)} to
  86. * create {@link ParameterValue}s.
  87. *
  88. * TODO: what Jelly pages does this object need for rendering UI?
  89. * TODO: {@link ParameterValue} needs to have some mechanism to expose values to the build
  90. * @see StringParameterDefinition
  91. */
  92. @ExportedBean(defaultVisibility=3)
  93. public abstract class ParameterDefinition implements
  94. Describable<ParameterDefinition>, ExtensionPoint, Serializable {
  95. private final String name;
  96. private final String description;
  97. public ParameterDefinition(String name) {
  98. this(name, null);
  99. }
  100. public ParameterDefinition(String name, String description) {
  101. this.name = name;
  102. this.description = description;
  103. }
  104. @Exported
  105. public String getType() {
  106. return this.getClass().getSimpleName();
  107. }
  108. @Exported
  109. public String getName() {
  110. return name;
  111. }
  112. @Exported
  113. public String getDescription() {
  114. return description;
  115. }
  116. /**
  117. * {@inheritDoc}
  118. */
  119. public ParameterDescriptor getDescriptor() {
  120. return (ParameterDescriptor)Hudson.getInstance().getDescriptorOrDie(getClass());
  121. }
  122. /**
  123. * Create a parameter value from a form submission.
  124. *
  125. * <p>
  126. * This method is invoked when the user fills in the parameter values in the HTML form
  127. * and submits it to the server.
  128. */
  129. public abstract ParameterValue createValue(StaplerRequest req, JSONObject jo);
  130. /**
  131. * Create a parameter value from a GET with query string.
  132. * If no value is available in the request, it returns a default value if possible, or null.
  133. *
  134. * <p>
  135. * Unlike {@link #createValue(StaplerRequest, JSONObject)}, this method is intended to support
  136. * the programmatic POST-ing of the build URL. This form is less expressive (as it doesn't support
  137. * the tree form), but it's more scriptable.
  138. *
  139. * <p>
  140. * If a {@link ParameterDefinition} can't really support this mode of creating a value,
  141. * you may just always return null.
  142. */
  143. public abstract ParameterValue createValue(StaplerRequest req);
  144. /**
  145. * Create a parameter value from the string given in the CLI.
  146. *
  147. * @param command
  148. * This is the command that got the parameter. You can use its {@link CLICommand#channel}
  149. * for interacting with the CLI JVM.
  150. * @throws AbortException
  151. * If the CLI processing should be aborted. Hudson will report the error message
  152. * without stack trace, and then exits this command. Useful for graceful termination.
  153. * @throws Exception
  154. * All the other exceptions cause the stack trace to be dumped, and then
  155. * the command exits with an error code.
  156. * @since 1.334
  157. */
  158. public ParameterValue createValue(CLICommand command, String value) throws IOException, InterruptedException {
  159. throw new AbortException("CLI parameter submission is not supported for the "+getClass()+" type. Please file a bug report for this");
  160. }
  161. /**
  162. * Returns default parameter value for this definition.
  163. *
  164. * @return default parameter value or null if no defaults are available
  165. * @since 1.253
  166. */
  167. @Exported
  168. public ParameterValue getDefaultParameterValue() {
  169. return null;
  170. }
  171. /**
  172. * Returns all the registered {@link ParameterDefinition} descriptors.
  173. */
  174. public static DescriptorExtensionList<ParameterDefinition,ParameterDescriptor> all() {
  175. return Hudson.getInstance().<ParameterDefinition,ParameterDescriptor>getDescriptorList(ParameterDefinition.class);
  176. }
  177. /**
  178. * A list of available parameter definition types
  179. * @deprecated as of 1.286
  180. * Use {@link #all()} for read access, and {@link Extension} for registration.
  181. */
  182. public static final DescriptorList<ParameterDefinition> LIST = new DescriptorList<ParameterDefinition>(ParameterDefinition.class);
  183. public abstract static class ParameterDescriptor extends
  184. Descriptor<ParameterDefinition> {
  185. protected ParameterDescriptor(Class<? extends ParameterDefinition> klazz) {
  186. super(klazz);
  187. }
  188. /**
  189. * Infers the type of the corresponding {@link ParameterDescriptor} from the outer class.
  190. * This version works when you follow the common convention, where a descriptor
  191. * is written as the static nested class of the describable class.
  192. *
  193. * @since 1.278
  194. */
  195. protected ParameterDescriptor() {
  196. }
  197. public String getValuePage() {
  198. return getViewPage(clazz, "index.jelly");
  199. }
  200. @Override
  201. public String getDisplayName() {
  202. return "Parameter";
  203. }
  204. }
  205. @Override
  206. public boolean equals(Object o) {
  207. if (this == o) {
  208. return true;
  209. }
  210. if (o == null || getClass() != o.getClass()) {
  211. return false;
  212. }
  213. ParameterDefinition that = (ParameterDefinition) o;
  214. if (name != null ? !name.equals(that.name) : that.name != null) {
  215. return false;
  216. }
  217. return true;
  218. }
  219. @Override
  220. public int hashCode() {
  221. return new HashCodeBuilder()
  222. .append(getName())
  223. .append(getClass())
  224. .toHashCode();
  225. }
  226. }