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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
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.tasks;
25
26 import hudson.AbortException;
27 import hudson.Launcher;
28 import hudson.Extension;
29 import hudson.ExtensionList;
30 import hudson.util.DescriptorList;
31 import hudson.model.AbstractBuild;
32 import hudson.model.AbstractProject;
33 import hudson.model.Action;
34 import hudson.model.Build;
35 import hudson.model.BuildListener;
36 import hudson.model.Descriptor;
37 import hudson.model.Project;
38 import hudson.model.CheckPoint;
39 import hudson.model.Run;
40
41 import java.io.IOException;
42 import java.util.Collection;
43 import java.util.List;
44 import java.util.AbstractList;
45 import java.util.Iterator;
46 import java.util.WeakHashMap;
47
48 /**
49 * One step of the whole build process.
50 *
51 * <h2>Persistence</h2>
52 * <p>
53 * These objects are persisted as a part of {@link Project} by XStream.
54 * The save operation happens without any notice, and the restore operation
55 * happens without calling the constructor, just like Java serialization.
56 *
57 * <p>
58 * So generally speaking, derived classes should use instance variables
59 * only for keeping configuration. You can still store objects you use
60 * for processing, like a parser of some sort, but they need to be marked
61 * as <tt>transient</tt>, and the code needs to be aware that they might
62 * be null (which is the case when you access the field for the first time
63 * the object is restored.)
64 *
65 * <h2>Lifecycle</h2>
66 * <p>
67 * Build steps are instantiated when the user saves the job configuration, and sticks
68 * around in memory until the job configuration is overwritten.
69 *
70 * @author Kohsuke Kawaguchi
71 */
72 public interface BuildStep {
73
74 /**
75 * Runs before the build begins.
76 *
77 * @return
78 * true if the build can continue, false if there was an error
79 * and the build needs to be aborted.
80 * <p>
81 * Using the return value to indicate success/failure should
82 * be considered deprecated, and implementations are encouraged
83 * to throw {@link AbortException} to indicate a failure.
84 */
85 boolean prebuild( AbstractBuild<?,?> build, BuildListener listener );
86
87 /**
88 * Runs the step over the given build and reports the progress to the listener.
89 *
90 * <p>
91 * A plugin can contribute the action object to {@link Build#getActions()}
92 * so that a 'report' becomes a part of the persisted data of {@link Build}.
93 * This is how JUnit plugin attaches the test report to a build page, for example.
94 *
95 * @return
96 * true if the build can continue, false if there was an error
97 * and the build needs to be aborted.
98 * <p>
99 * Using the return value to indicate success/failure should
100 * be considered deprecated, and implementations are encouraged
101 * to throw {@link AbortException} to indicate a failure.
102 *
103 * @throws InterruptedException
104 * If the build is interrupted by the user (in an attempt to abort the build.)
105 * Normally the {@link BuildStep} implementations may simply forward the exception
106 * it got from its lower-level functions.
107 * @throws IOException
108 * If the implementation wants to abort the processing when an {@link IOException}
109 * happens, it can simply propagate the exception to the caller. This will cause
110 * the build to fail, with the default error message.
111 * Implementations are encouraged to catch {@link IOException} on its own to
112 * provide a better error message, if it can do so, so that users have better
113 * understanding on why it failed.
114 */
115 boolean perform(AbstractBuild<?,?> build, Launcher launcher, BuildListener listener) throws InterruptedException, IOException;
116
117 /**
118 * @deprecated as of 1.341.
119 * Use {@link #getProjectActions(AbstractProject)} instead.
120 */
121 Action getProjectAction(AbstractProject<?,?> project);
122
123 /**
124 * Returns action objects if this {@link BuildStep} has actions
125 * to contribute to a {@link Project}.
126 *
127 * <p>
128 * {@link Project} calls this method for every {@link BuildStep} that
129 * it owns when the rendering is requested.
130 *
131 * <p>
132 * This action can have optional <tt>jobMain.jelly</tt> view, which will be
133 * aggregated into the main panel of the job top page. The jelly file
134 * should have an &lt;h2> tag that shows the section title, followed by some
135 * block elements to render the details of the section.
136 *
137 * @param project
138 * {@link Project} that owns this build step,
139 * since {@link BuildStep} object doesn't usually have this "parent" pointer.
140 *
141 * @return
142 * can be empty but never null.
143 */
144 Collection<? extends Action> getProjectActions(AbstractProject<?,?> project);
145
146
147 /**
148 * Declares the scope of the synchronization monitor this {@link BuildStep} expects from outside.
149 *
150 * <p>
151 * This method is introduced for preserving compatibility with plugins written for earlier versions of Hudson,
152 * which never run multiple builds of the same job in parallel. Such plugins often assume that the outcome
153 * of the previous build is completely available, which is no longer true when we do concurrent builds.
154 *
155 * <p>
156 * To minimize the necessary code change for such plugins, {@link BuildStep} implementations can request
157 * Hudson to externally perform synchronization before executing them. This behavior is as follows:
158 *
159 * <dl>
160 * <dt>{@link BuildStepMonitor#BUILD}
161 * <dd>
162 * This {@link BuildStep} is only executed after the previous build is fully
163 * completed (thus fully restoring the earlier semantics of one build at a time.)
164 *
165 * <dt>{@link BuildStepMonitor#STEP}
166 * <dd>
167 * This {@link BuildStep} is only executed after the same step in the previous build is completed.
168 * For build steps that use a weaker assumption and only rely on the output from the same build step of
169 * the early builds, this improves the concurrency.
170 *
171 * <dt>{@link BuildStepMonitor#NONE}
172 * <dd>
173 * No external synchronization is performed on this build step. This is the most efficient, and thus
174 * <b>the recommended value for newer plugins</b>. Wherever necessary, you can directly use {@link CheckPoint}s
175 * to perform necessary synchronizations.
176 * </dl>
177 *
178 * <h2>Migrating Older Implementation</h2>
179 * <p>
180 * If you are migrating {@link BuildStep} implementations written for earlier versions of Hudson,
181 * here's what you can do:
182 *
183 * <ul>
184 * <li>
185 * Just return {@link BuildStepMonitor#BUILD} to demand the backward compatible behavior from Hudson,
186 * and make no other changes to the code. This will prevent users from reaping the benefits of concurrent
187 * builds, but at least your plugin will work correctly, and therefore this is a good easy first step.
188 * <li>
189 * If your build step doesn't use anything from a previous build (for example, if you don't even call
190 * {@link Run#getPreviousBuild()}), then you can return {@link BuildStepMonitor#NONE} without making further
191 * code changes and you are done with migration.
192 * <li>
193 * If your build step only depends on {@link Action}s that you added in the previous build by yourself,
194 * then you only need {@link BuildStepMonitor#STEP} scope synchronization. Return it from this method
195 * ,and you are done with migration without any further code changes.
196 * <li>
197 * If your build step makes more complex assumptions, return {@link BuildStepMonitor#NONE} and use
198 * {@link CheckPoint}s directly in your code. The general idea is to call {@link CheckPoint#block()} before
199 * you try to access the state from the previous build.
200 * </ul>
201 *
202 * <h2>Note to caller</h2>
203 * <p>
204 * For plugins written against earlier versions of Hudson, calling this method results in
205 * {@link AbstractMethodError}.
206 *
207 * @since 1.319
208 */
209 BuildStepMonitor getRequiredMonitorService();
210
211 /**
212 * List of all installed builders.
213 *
214 * Builders are invoked to perform the build itself.
215 *
216 * @deprecated as of 1.286.
217 * Use {@link Builder#all()} for read access, and use
218 * {@link Extension} for registration.
219 */
220 List<Descriptor<Builder>> BUILDERS = new DescriptorList<Builder>(Builder.class);
221
222 /**
223 * List of all installed publishers.
224 *
225 * Publishers are invoked after the build is completed, normally to perform
226 * some post-actions on build results, such as sending notifications, collecting
227 * results, etc.
228 *
229 * @see PublisherList#addNotifier(Descriptor)
230 * @see PublisherList#addRecorder(Descriptor)
231 *
232 * @deprecated as of 1.286.
233 * Use {@link Publisher#all()} for read access, and use
234 * {@link Extension} for registration.
235 */
236 PublisherList PUBLISHERS = new PublisherList();
237
238 /**
239 * List of publisher descriptor.
240 */
241 final class PublisherList extends AbstractList<Descriptor<Publisher>> {
242 /**
243 * {@link Descriptor}s are actually stored in here.
244 * Since {@link PublisherList} lives longer than {@link jenkins.model.Jenkins} we cannot directly use {@link ExtensionList}.
245 */
246 private final DescriptorList<Publisher> core = new DescriptorList<Publisher>(Publisher.class);
247
248 /**
249 * For descriptors that are manually registered, remember what kind it was since
250 * older plugins don't extend from neither {@link Recorder} nor {@link Notifier}.
251 */
252 /*package*/ static final WeakHashMap<Descriptor<Publisher>,Class<? extends Publisher>/*either Recorder.class or Notifier.class*/>
253 KIND = new WeakHashMap<Descriptor<Publisher>, Class<? extends Publisher>>();
254
255 private PublisherList() {
256 }
257
258 /**
259 * Adds a new publisher descriptor, which (generally speaking)
260 * shouldn't alter the build result, but just report the build result
261 * by some means, such as e-mail, IRC, etc.
262 *
263 * <p>
264 * This method adds the descriptor after all the "recorders".
265 *
266 * @see #addRecorder(Descriptor)
267 */
268 public void addNotifier( Descriptor<Publisher> d ) {
269 KIND.put(d,Notifier.class);
270 core.add(d);
271 }
272
273 /**
274 * Adds a new publisher descriptor, which (generally speaking)
275 * alter the build result based on some artifacts of the build.
276 *
277 * <p>
278 * This method adds the descriptor before all the "notifiers".
279 *
280 * @see #addNotifier(Descriptor)
281 */
282 public void addRecorder( Descriptor<Publisher> d ) {
283 KIND.put(d,Recorder.class);
284 core.add(d);
285 }
286
287 @Override
288 public boolean add(Descriptor<Publisher> d) {
289 return !contains(d) && core.add(d);
290 }
291
292 @Override
293 public void add(int index, Descriptor<Publisher> d) {
294 if(!contains(d)) core.add(d);
295 }
296
297 public Descriptor<Publisher> get(int index) {
298 return core.get(index);
299 }
300
301 public int size() {
302 return core.size();
303 }
304
305 @Override
306 public Iterator<Descriptor<Publisher>> iterator() {
307 return core.iterator();
308 }
309
310 @Override
311 public boolean remove(Object o) {
312 return core.remove(o);
313 }
314 }
315 }
316