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

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
26 import hudson.DescriptorExtensionList;
27 import hudson.Extension;
28 import hudson.ExtensionPoint;
29 import hudson.AbortException;
30 import hudson.cli.CLICommand;
31 import hudson.util.DescriptorList;
32
33 import java.io.Serializable;
34 import java.io.IOException;
35
36 import jenkins.model.Jenkins;
37 import net.sf.json.JSONObject;
38
39 import org.kohsuke.stapler.StaplerRequest;
40 import org.kohsuke.stapler.export.Exported;
41 import org.kohsuke.stapler.export.ExportedBean;
42
43 /**
44 * Defines a parameter for a build.
45 *
46 * <p>
47 * In Hudson, a user can configure a job to require parameters for a build.
48 * For example, imagine a test job that takes the bits to be tested as a parameter.
49 *
50 * <p>
51 * The actual meaning and the purpose of parameters are entirely up to users, so
52 * what the concrete parameter implmentation is pluggable. Write subclasses
53 * in a plugin and put {@link Extension} on the descriptor to register them.
54 *
55 * <p>
56 * Three classes are used to model build parameters. First is the
57 * {@link ParameterDescriptor}, which tells Hudson what kind of implementations are
58 * available. From {@link ParameterDescriptor#newInstance(StaplerRequest, JSONObject)},
59 * Hudson creates {@link ParameterDefinition}s based on the job configuration.
60 * For example, if the user defines two string parameters "database-type" and
61 * "appserver-type", we'll get two {@link StringParameterDefinition} instances
62 * with their respective names.
63 *
64 * <p>
65 * When a job is configured with {@link ParameterDefinition} (or more precisely,
66 * {@link ParametersDefinitionProperty}, which in turns retains {@link ParameterDefinition}s),
67 * user would have to enter the values for the defined build parameters.
68 * The {@link #createValue(StaplerRequest, JSONObject)} method is used to convert this
69 * form submission into {@link ParameterValue} objects, which are then accessible
70 * during a build.
71 *
72 *
73 *
74 * <h2>Persistence</h2>
75 * <p>
76 * Instances of {@link ParameterDefinition}s are persisted into job <tt>config.xml</tt>
77 * through XStream.
78 *
79 *
80 * <h2>Assocaited Views</h2>
81 * <h4>config.jelly</h4>
82 * <p>
83 * {@link ParameterDefinition} class uses <tt>config.jelly</tt> to provide contribute a form
84 * fragment in the job configuration screen. Values entered there is fed back to
85 * {@link ParameterDescriptor#newInstance(StaplerRequest, JSONObject)} to create {@link ParameterDefinition}s.
86 *
87 * <h4>index.jelly</h4>
88 * The <tt>index.jelly</tt> view contributes a form fragment in the page where the user
89 * enters actual values of parameters for a build. The result of this form submission
90 * is then fed to {@link ParameterDefinition#createValue(StaplerRequest, JSONObject)} to
91 * create {@link ParameterValue}s.
92 *
93 * TODO: what Jelly pages does this object need for rendering UI?
94 * TODO: {@link ParameterValue} needs to have some mechanism to expose values to the build
95 * @see StringParameterDefinition
96 */
97 @ExportedBean(defaultVisibility=3)
98 public abstract class ParameterDefinition implements
99 Describable<ParameterDefinition>, ExtensionPoint, Serializable {
100
101 private final String name;
102
103 private final String description;
104
105 public ParameterDefinition(String name) {
106 this(name, null);
107 }
108
109 public ParameterDefinition(String name, String description) {
110 this.name = name;
111 this.description = description;
112 }
113
114 /**
115 * Create a new instance of this parameter definition and use the passed
116 * parameter value as the default value.
117 *
118 * @since 1.405
119 */
120 public ParameterDefinition copyWithDefaultValue(ParameterValue defaultValue) {
121 // By default, just return this again
122 return this;
123 }
124
125 @Exported
126 public String getType() {
127 return this.getClass().getSimpleName();
128 }
129
130 @Exported
131 public String getName() {
132 return name;
133 }
134
135 @Exported
136 public String getDescription() {
137 return description;
138 }
139
140 /**
141 * {@inheritDoc}
142 */
143 public ParameterDescriptor getDescriptor() {
144 return (ParameterDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass());
145 }
146
147 /**
148 * Create a parameter value from a form submission.
149 *
150 * <p>
151 * This method is invoked when the user fills in the parameter values in the HTML form
152 * and submits it to the server.
153 */
154 public abstract ParameterValue createValue(StaplerRequest req, JSONObject jo);
155
156 /**
157 * Create a parameter value from a GET with query string.
158 * If no value is available in the request, it returns a default value if possible, or null.
159 *
160 * <p>
161 * Unlike {@link #createValue(StaplerRequest, JSONObject)}, this method is intended to support
162 * the programmatic POST-ing of the build URL. This form is less expressive (as it doesn't support
163 * the tree form), but it's more scriptable.
164 *
165 * <p>
166 * If a {@link ParameterDefinition} can't really support this mode of creating a value,
167 * you may just always return null.
168 *
169 * @throws IllegalStateException
170 * If the parameter is deemed required but was missing in the submission.
171 */
172 public abstract ParameterValue createValue(StaplerRequest req);
173
174
175 /**
176 * Create a parameter value from the string given in the CLI.
177 *
178 * @param command
179 * This is the command that got the parameter. You can use its {@link CLICommand#checkChannel()}
180 * for interacting with the CLI JVM.
181 * @throws AbortException
182 * If the CLI processing should be aborted. Hudson will report the error message
183 * without stack trace, and then exits this command. Useful for graceful termination.
184 * @throws Exception
185 * All the other exceptions cause the stack trace to be dumped, and then
186 * the command exits with an error code.
187 * @since 1.334
188 */
189 public ParameterValue createValue(CLICommand command, String value) throws IOException, InterruptedException {
190 throw new AbortException("CLI parameter submission is not supported for the "+getClass()+" type. Please file a bug report for this");
191 }
192
193 /**
194 * Returns default parameter value for this definition.
195 *
196 * @return default parameter value or null if no defaults are available
197 * @since 1.253
198 */
199 @Exported
200 public ParameterValue getDefaultParameterValue() {
201 return null;
202 }
203
204 /**
205 * Returns all the registered {@link ParameterDefinition} descriptors.
206 */
207 public static DescriptorExtensionList<ParameterDefinition,ParameterDescriptor> all() {
208 return Jenkins.getInstance().<ParameterDefinition,ParameterDescriptor>getDescriptorList(ParameterDefinition.class);
209 }
210
211 /**
212 * A list of available parameter definition types
213 * @deprecated as of 1.286
214 * Use {@link #all()} for read access, and {@link Extension} for registration.
215 */
216 public static final DescriptorList<ParameterDefinition> LIST = new DescriptorList<ParameterDefinition>(ParameterDefinition.class);
217
218 public abstract static class ParameterDescriptor extends
219 Descriptor<ParameterDefinition> {
220
221 protected ParameterDescriptor(Class<? extends ParameterDefinition> klazz) {
222 super(klazz);
223 }
224
225 /**
226 * Infers the type of the corresponding {@link ParameterDescriptor} from the outer class.
227 * This version works when you follow the common convention, where a descriptor
228 * is written as the static nested class of the describable class.
229 *
230 * @since 1.278
231 */
232 protected ParameterDescriptor() {
233 }
234
235 public String getValuePage() {
236 return getViewPage(clazz, "index.jelly");
237 }
238
239 @Override
240 public String getDisplayName() {
241 return "Parameter";
242 }
243 }
244 }
245