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

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi, 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.listeners;
25
26 import hudson.ExtensionPoint;
27 import hudson.ExtensionListView;
28 import hudson.Extension;
29 import hudson.ExtensionList;
30 import hudson.FilePath;
31 import hudson.Launcher;
32 import hudson.model.AbstractBuild;
33 import hudson.model.BuildListener;
34 import hudson.model.Environment;
35 import hudson.model.JobProperty;
36 import hudson.model.Run;
37 import hudson.model.TaskListener;
38 import jenkins.model.Jenkins;
39 import hudson.scm.SCM;
40 import hudson.tasks.BuildWrapper;
41 import hudson.util.CopyOnWriteList;
42 import org.jvnet.tiger_types.Types;
43
44 import java.io.File;
45 import java.io.IOException;
46 import java.lang.reflect.ParameterizedType;
47 import java.lang.reflect.Type;
48 import java.util.logging.Level;
49 import java.util.logging.Logger;
50 import javax.annotation.Nonnull;
51
52 /**
53 * Receives notifications about builds.
54 *
55 * <p>
56 * Listener is always Hudson-wide, so once registered it gets notifications for every build
57 * that happens in this Hudson.
58 *
59 * <p>
60 * This is an abstract class so that methods added in the future won't break existing listeners.
61 *
62 * @author Kohsuke Kawaguchi
63 * @since 1.145
64 */
65 public abstract class RunListener<R extends Run> implements ExtensionPoint {
66 public final Class<R> targetType;
67
68 protected RunListener(Class<R> targetType) {
69 this.targetType = targetType;
70 }
71
72 protected RunListener() {
73 Type type = Types.getBaseClass(getClass(), RunListener.class);
74 if (type instanceof ParameterizedType)
75 targetType = Types.erasure(Types.getTypeArgument(type,0));
76 else
77 throw new IllegalStateException(getClass()+" uses the raw type for extending RunListener");
78 }
79
80 /**
81 * Called after a build is completed.
82 *
83 * @param r
84 * The completed build.
85 * @param listener
86 * The listener for this build. This can be used to produce log messages, for example,
87 * which becomes a part of the "console output" of this build. But when this method runs,
88 * the build is considered completed, so its status cannot be changed anymore.
89 */
90 public void onCompleted(R r, @Nonnull TaskListener listener) {}
91
92 /**
93 * Called after a build is moved to the {@link Run.State#COMPLETED} state.
94 *
95 * <p>
96 * At this point, all the records related to a build is written down to the disk. As such,
97 * {@link TaskListener} is no longer available. This happens later than {@link #onCompleted(Run, TaskListener)}.
98 */
99 public void onFinalized(R r) {}
100
101 /**
102 * Called when a build is started (i.e. it was in the queue, and will now start running
103 * on an executor)
104 *
105 * @param r
106 * The started build.
107 * @param listener
108 * The listener for this build. This can be used to produce log messages, for example,
109 * which becomes a part of the "console output" of this build.
110 */
111 public void onStarted(R r, TaskListener listener) {}
112
113 /**
114 * Runs before the {@link SCM#checkout(AbstractBuild, Launcher, FilePath, BuildListener, File)} runs, and performs a set up.
115 * Can contribute additional properties/env vars to the environment.
116 *
117 * <p>
118 * A typical strategy is for implementations to check {@link JobProperty}s and other configuration
119 * of the project to determine the environment to inject, which allows you to achieve the equivalent of
120 * {@link BuildWrapper}, but without UI.
121 *
122 * @param build
123 * The build in progress for which an {@link Environment} object is created.
124 * Never null.
125 * @param launcher
126 * This launcher can be used to launch processes for this build.
127 * If the build runs remotely, launcher will also run a job on that remote machine.
128 * Never null.
129 * @param listener
130 * Can be used to send any message.
131 * @return
132 * non-null if the build can continue, null if there was an error
133 * and the build needs to be aborted.
134 * @throws IOException
135 * terminates the build abnormally. Hudson will handle the exception
136 * and reports a nice error message.
137 * @since 1.410
138 */
139 public Environment setUpEnvironment( AbstractBuild build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException {
140 return new Environment() {};
141 }
142
143 /**
144 * Called right before a build is going to be deleted.
145 *
146 * @param r The build.
147 */
148 public void onDeleted(R r) {}
149
150 /**
151 * Registers this object as an active listener so that it can start getting
152 * callbacks invoked.
153 *
154 * @deprecated as of 1.281
155 * Put {@link Extension} on your class to get it auto-registered.
156 */
157 public void register() {
158 all().add(this);
159 }
160
161 /**
162 * Reverse operation of {@link #register()}.
163 */
164 public void unregister() {
165 all().remove(this);
166 }
167
168 /**
169 * List of registered listeners.
170 * @deprecated as of 1.281
171 * Use {@link #all()} for read access, and use {@link Extension} for registration.
172 */
173 public static final CopyOnWriteList<RunListener> LISTENERS = ExtensionListView.createCopyOnWriteList(RunListener.class);
174
175 /**
176 * Fires the {@link #onCompleted(Run, TaskListener)} event.
177 */
178 public static void fireCompleted(Run r, @Nonnull TaskListener listener) {
179 for (RunListener l : all()) {
180 if(l.targetType.isInstance(r))
181 try {
182 l.onCompleted(r,listener);
183 } catch (Throwable e) {
184 report(e);
185 }
186 }
187 }
188
189 /**
190 * Fires the {@link #onStarted(Run, TaskListener)} event.
191 */
192 public static void fireStarted(Run r, TaskListener listener) {
193 for (RunListener l : all()) {
194 if(l.targetType.isInstance(r))
195 try {
196 l.onStarted(r,listener);
197 } catch (Exception e) {
198 report(e);
199 }
200 }
201 }
202
203 /**
204 * Fires the {@link #onFinalized(Run)} event.
205 */
206 public static void fireFinalized(Run r) {
207 if (Jenkins.getInstance() == null) {
208 return;
209 }
210 for (RunListener l : all()) {
211 if(l.targetType.isInstance(r))
212 try {
213 l.onFinalized(r);
214 } catch (Exception e) {
215 report(e);
216 }
217 }
218 }
219
220 /**
221 * Fires the {@link #onFinalized(Run)} event.
222 */
223 public static void fireDeleted(Run r) {
224 for (RunListener l : all()) {
225 if(l.targetType.isInstance(r))
226 try {
227 l.onDeleted(r);
228 } catch (Exception e) {
229 report(e);
230 }
231 }
232 }
233
234 /**
235 * Returns all the registered {@link RunListener} descriptors.
236 */
237 public static ExtensionList<RunListener> all() {
238 return Jenkins.getInstance().getExtensionList(RunListener.class);
239 }
240
241 private static void report(Throwable e) {
242 LOGGER.log(Level.WARNING, "RunListener failed",e);
243 }
244
245 private static final Logger LOGGER = Logger.getLogger(RunListener.class.getName());
246 }
247