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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2010, Sun Microsystems, Inc., Kohsuke Kawaguchi, Yahoo! Inc.
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.ExtensionPoint;
27 import hudson.Launcher;
28 import hudson.DescriptorExtensionList;
29 import hudson.LauncherDecorator;
30 import hudson.console.ConsoleLogFilter;
31 import hudson.model.*;
32 import hudson.model.Run.RunnerAbortedException;
33 import hudson.util.ArgumentListBuilder;
34 import jenkins.model.Jenkins;
35
36 import java.io.IOException;
37 import java.io.OutputStream;
38 import java.util.Collection;
39 import java.util.Collections;
40 import java.util.Map;
41 import java.util.Set;
42
43 /**
44 * Pluggability point for performing pre/post actions for the build process.
45 *
46 * <p>
47 * This extension point enables a plugin to set up / tear down additional
48 * services needed to perform a build, such as setting up local X display,
49 * or launching and stopping application servers for testing.
50 *
51 * <p>
52 * An instance of {@link BuildWrapper} is associated with a {@link Project}
53 * with configuration information as its state. An instance is persisted
54 * along with {@link Project}.
55 *
56 * <p>
57 * {@link BuildWrapper}s are instantiated when the user saves the job configuration, and sticks
58 * around in memory until the job configuration is overwritten.
59 *
60 *
61 * <p>
62 * The {@link #setUp(Build,Launcher,BuildListener)} method is invoked for each build.
63 *
64 * <p>
65 * {@link BuildWrapper} requires an user consent (in terms of a checkbox) to work.
66 * If this is not desirable, see {@link hudson.model.Environment} for other ways
67 * to inject Environments to builds.
68 *
69 * @author Kohsuke Kawaguchi
70 */
71 public abstract class BuildWrapper extends AbstractDescribableImpl<BuildWrapper> implements ExtensionPoint {
72 /**
73 * Represents the environment set up by {@link BuildWrapper#setUp(Build,Launcher,BuildListener)}.
74 *
75 * <p>
76 * It is expected that the subclasses of {@link BuildWrapper} extends this
77 * class and implements its own semantics.
78 */
79 public abstract class Environment extends hudson.model.Environment {
80 /**
81 * Runs after the {@link Builder} completes, and performs a tear down.
82 *
83 * <p>
84 * This method is invoked even when the build failed, so that the
85 * clean up operation can be performed regardless of the build result
86 * (for example, you'll want to stop application server even if a build
87 * fails.) {@link Build#getResult} in this case will return Result.FAILURE
88 * (since 1.339), and a null result indicates SUCCESS-so-far (post-build
89 * actions may still affect the final result).
90 *
91 * @param build
92 * The same {@link Build} object given to the set up method.
93 * @param listener
94 * The same {@link BuildListener} object given to the set up method.
95 * @return
96 * true if the build can continue, false if there was an error
97 * and the build needs to be aborted.
98 * @throws IOException
99 * terminates the build abnormally. Hudson will handle the exception
100 * and reports a nice error message.
101 * @since 1.150
102 */
103 public boolean tearDown( AbstractBuild build, BuildListener listener ) throws IOException, InterruptedException {
104 if (build instanceof Build)
105 return tearDown((Build)build, listener);
106 else
107 return true;
108 }
109
110 /**
111 * @deprecated since 2007-10-28.
112 * Use {@link #tearDown(AbstractBuild, BuildListener)} instead.
113 */
114 @Deprecated
115 public boolean tearDown( Build build, BuildListener listener ) throws IOException, InterruptedException {
116 return true;
117 }
118 }
119
120 /**
121 * Runs before the {@link Builder} runs (but after the checkout has occurred), and performs a set up.
122 *
123 * @param build
124 * The build in progress for which an {@link Environment} object is created.
125 * Never null.
126 * @param launcher
127 * This launcher can be used to launch processes for this build.
128 * If the build runs remotely, launcher will also run a job on that remote machine.
129 * Never null.
130 * @param listener
131 * Can be used to send any message.
132 * @return
133 * non-null if the build can continue, null if there was an error
134 * and the build needs to be aborted.
135 * @throws IOException
136 * terminates the build abnormally. Hudson will handle the exception
137 * and reports a nice error message.
138 * @since 1.150
139 */
140 public Environment setUp( AbstractBuild build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException {
141 if (build instanceof Build)
142 return setUp((Build)build,launcher,listener);
143 else
144 throw new AssertionError("The plugin '" + this.getClass().getName() + "' still uses " +
145 "deprecated setUp(Build,Launcher,BuildListener) method. " +
146 "Update the plugin to use setUp(AbstractBuild, Launcher, BuildListener) instead.");
147 }
148
149 /**
150 * @deprecated since 2007-10-28.
151 * Use {@link #setUp(AbstractBuild, Launcher, BuildListener)} instead.
152 */
153 @Deprecated
154 public Environment setUp( Build build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException {
155 throw new UnsupportedOperationException(getClass()+" needs to implement the setUp method");
156 }
157
158 /**
159 * Provides an opportunity for a {@link BuildWrapper} to decorate a {@link Launcher} to be used in the build.
160 *
161 * <p>
162 * This hook is called very early on in the build (even before {@link #setUp(AbstractBuild, Launcher, BuildListener)} is invoked.)
163 * The typical use of {@link Launcher} decoration involves in modifying the environment that processes run,
164 * such as the use of sudo/pfexec/chroot, or manipulating environment variables.
165 *
166 * <p>
167 * The default implementation is no-op, which just returns the {@code launcher} parameter as-is.
168 *
169 * @param build
170 * The build in progress for which this {@link BuildWrapper} is called. Never null.
171 * @param launcher
172 * The default launcher. Never null. This method is expected to wrap this launcher.
173 * This makes sure that when multiple {@link BuildWrapper}s attempt to decorate the same launcher
174 * it will sort of work. But if you are developing a plugin where such collision is not a concern,
175 * you can also simply discard this {@link Launcher} and create an entirely different {@link Launcher}
176 * and return it, too.
177 * @param listener
178 * Connected to the build output. Never null. Can be used for error reporting.
179 * @return
180 * Must not be null. If a fatal error happens, throw an exception.
181 * @throws RunnerAbortedException
182 * If a fatal error is detected but the implementation handled it gracefully, throw this exception
183 * to suppress stack trace.
184 * @since 1.280
185 * @see LauncherDecorator
186 */
187 public Launcher decorateLauncher(AbstractBuild build, Launcher launcher, BuildListener listener) throws IOException, InterruptedException, RunnerAbortedException {
188 return launcher;
189 }
190
191 /**
192 * Provides an opportunity for a {@link BuildWrapper} to decorate the {@link BuildListener} logger to be used by the build.
193 *
194 * <p>
195 * This hook is called very early on in the build (even before {@link #setUp(AbstractBuild, Launcher, BuildListener)} is invoked.)
196 *
197 * <p>
198 * The default implementation is no-op, which just returns the {@code logger} parameter as-is.
199 * <p>({@link ArgumentListBuilder#add(String, boolean)} is a simpler way to suppress a single password.)
200 * @param build
201 * The build in progress for which this {@link BuildWrapper} is called. Never null.
202 * @param logger
203 * The default logger. Never null. This method is expected to wrap this logger.
204 * This makes sure that when multiple {@link BuildWrapper}s attempt to decorate the same logger
205 * it will sort of work.
206 * @return
207 * Must not be null. If a fatal error happens, throw an exception.
208 * @throws RunnerAbortedException
209 * If a fatal error is detected but the implementation handled it gracefully, throw this exception
210 * to suppress stack trace.
211 * @since 1.374
212 * @see ConsoleLogFilter
213 */
214 public OutputStream decorateLogger(AbstractBuild build, OutputStream logger) throws IOException, InterruptedException, RunnerAbortedException {
215 return logger;
216 }
217
218 /**
219 * Provides an opportunity for a {@link BuildWrapper} to perform some actions before SCM checkout.
220 *
221 * <p>
222 * This hook is called early on in the build (before {@link #setUp(AbstractBuild, Launcher, BuildListener)},
223 * but after {@link #decorateLauncher(AbstractBuild, Launcher, BuildListener)} is invoked.)
224 * The typical use is delete existing workspace before new build starts etc.
225 *
226 * <p>
227 * By the time this method is called, the workspace is assigned to the build, which can be obtained
228 * via {@code build.getWorkspace()}.
229 *
230 * <p>
231 * The default implementation is no-op.
232 *
233 * @param build
234 * The build in progress for which this {@link BuildWrapper} is called. Never null.
235 * @param launcher
236 * The launcher. Never null.
237 * @param listener
238 * Connected to the build output. Never null. Can be used for error reporting.
239 * @since 1.399
240 */
241 public void preCheckout(AbstractBuild build, Launcher launcher, BuildListener listener) throws IOException, InterruptedException{
242 }
243
244 /**
245 * {@link Action} to be displayed in the job page.
246 *
247 * @param job
248 * This object owns the {@link BuildWrapper}. The returned action will be added to this object.
249 * @return
250 * null if there's no such action.
251 * @since 1.226
252 * @deprecated
253 * Use {@link #getProjectActions(AbstractProject)} instead.
254 */
255 public Action getProjectAction(AbstractProject job) {
256 return null;
257 }
258
259 /**
260 * {@link Action}s to be displayed in the job page.
261 *
262 * @param job
263 * This object owns the {@link BuildWrapper}. The returned action will be added to this object.
264 * @return
265 * can be empty but never null
266 * @since 1.341
267 */
268 public Collection<? extends Action> getProjectActions(AbstractProject job) {
269 // delegate to getJobAction (singular) for backward compatible behavior
270 Action a = getProjectAction(job);
271 if (a==null) return Collections.emptyList();
272 return Collections.singletonList(a);
273 }
274
275 /**
276 * Called to define {@linkplain AbstractBuild#getBuildVariables()}.
277 *
278 * This provides an opportunity for a BuildWrapper to append any additional
279 * build variables defined for the current build.
280 *
281 * @param build
282 * The build in progress for which this {@link BuildWrapper} is called. Never null.
283 * @param variables
284 * Contains existing build variables. Add additional build variables that you contribute
285 * to this map.
286 */
287 public void makeBuildVariables(AbstractBuild build, Map<String,String> variables) {
288 // noop
289 }
290
291 /**
292 * Called to define sensitive build variables. This provides an opportunity
293 * for a BuildWrapper to denote the names of variables that are sensitive in
294 * nature and should not be exposed in output.
295 *
296 * @param build
297 * The build in progress for which this {@link BuildWrapper} is called. Never null.
298 * @param sensitiveVariables
299 * Contains names of sensitive build variables. Names of sensitive variables
300 * that were added with {@link #makeBuildVariables(hudson.model.AbstractBuild, java.util.Map)}
301 * @since 1.378
302 */
303 public void makeSensitiveBuildVariables(AbstractBuild build, Set<String> sensitiveVariables) {
304 // noop
305 }
306
307 /**
308 * Returns all the registered {@link BuildWrapper} descriptors.
309 */
310 // for compatibility we can't use BuildWrapperDescriptor
311 public static DescriptorExtensionList<BuildWrapper,Descriptor<BuildWrapper>> all() {
312 // use getDescriptorList and not getExtensionList to pick up legacy instances
313 return Jenkins.getInstance().<BuildWrapper,Descriptor<BuildWrapper>>getDescriptorList(BuildWrapper.class);
314 }
315 }
316