File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\maven-plugin\src\main\java\hudson\maven\MavenReporter.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.maven;
25
26 import hudson.ExtensionPoint;
27 import hudson.Launcher;
28 import hudson.model.Action;
29 import hudson.model.BuildListener;
30 import hudson.model.Describable;
31 import jenkins.model.Jenkins;
32 import hudson.tasks.BuildStep;
33 import hudson.tasks.Publisher;
34 import org.apache.maven.plugin.MojoExecutionException;
35 import org.apache.maven.plugin.MojoFailureException;
36 import org.apache.maven.project.MavenProject;
37 import org.apache.maven.reporting.MavenReport;
38
39 import java.io.IOException;
40 import java.io.Serializable;
41 import java.util.Collection;
42 import java.util.Collections;
43
44 /**
45 * Listens to the build execution of {@link MavenBuild},
46 * and normally records some information and exposes thoses
47 * in {@link MavenBuild} later.
48 *
49 * <p>
50 * {@link MavenReporter} is first instanciated on the master.
51 * Then during the build, it is serialized and sent over into
52 * the maven process by serialization. Reporters will then receive
53 * event callbacks as mojo execution progresses. Those event callbacks
54 * are the ones that take {@link MavenBuildProxy}.
55 *
56 * <p>
57 * Once the maven build completes normally or abnormally, the reporters
58 * will be sent back to the master by serialization again, then
59 * have its {@link #end(MavenBuild, Launcher, BuildListener)} method invoked.
60 * This is a good opportunity to perform the post-build action.
61 *
62 * <p>
63 * This is the {@link MavenBuild} equivalent of {@link BuildStep}. Instances
64 * of {@link MavenReporter}s are persisted with {@link MavenModule}/{@link MavenModuleSet},
65 * possibly with configuration specific to that job.
66 *
67 *
68 * <h2>Callback Firing Sequence</h2>
69 * <p>
70 * The callback methods are invoked in the following order:
71 *
72 * <pre>
73 * SEQUENCE := preBuild MODULE* postBuild end
74 * MODULE := enterModule MOJO+ leaveModule
75 * MOJO := preExecute postExecute
76 * </pre>
77 *
78 * <p>
79 * When an error happens, the call sequence could be terminated at any point
80 * and no further callback methods may be invoked.
81 *
82 *
83 * <h2>Action</h2>
84 * <p>
85 * {@link MavenReporter} can {@link MavenBuild#addAction(Action) contribute}
86 * {@link Action} to {@link MavenBuild} so that the report can be displayed
87 * in the web UI.
88 *
89 * <p>
90 * Such action can also implement {@link AggregatableAction} if it further
91 * wishes to contribute a separate action to {@link MavenModuleSetBuild}.
92 * This mechanism is usually used to provide aggregated report for all the
93 * module builds.
94 *
95 * @author Kohsuke Kawaguchi
96 * @see MavenReporters
97 */
98 public abstract class MavenReporter implements Describable<MavenReporter>, ExtensionPoint, Serializable, MavenProjectActionBuilder {
99
100 private static final long serialVersionUID = 7987776766278437534L;
101
102 /**
103 * Called before the actual maven2 execution begins.
104 *
105 * @param pom
106 * Represents the POM to be executed.
107 * @return
108 * true if the build can continue, false if there was an error
109 * and the build needs to be aborted.
110 * @throws InterruptedException
111 * If the build is interrupted by the user (in an attempt to abort the build.)
112 * Normally the {@link MavenReporter} implementations may simply forward the exception
113 * it got from its lower-level functions.
114 * @throws IOException
115 * If the implementation wants to abort the processing when an {@link IOException}
116 * happens, it can simply propagate the exception to the caller. This will cause
117 * the build to fail, with the default error message.
118 * Implementations are encouraged to catch {@link IOException} on its own to
119 * provide a better error message, if it can do so, so that users have better
120 * understanding on why it failed.
121 */
122 public boolean preBuild(MavenBuildProxy build, MavenProject pom, BuildListener listener) throws InterruptedException, IOException {
123 return true;
124 }
125
126 /**
127 * Called when the build enters a next {@link MavenProject}.
128 *
129 * <p>
130 * When the current build is a multi-module reactor build, every time the build
131 * moves on to the next module, this method will be invoked.
132 *
133 * <p>
134 * Note that as of Maven 2.0.4, Maven does not perform any smart optimization
135 * on the order of goal executions. Therefore, the same module might be entered more than
136 * once during the build.
137 *
138 * @return
139 * See {@link #preBuild}
140 * @throws InterruptedException
141 * See {@link #preBuild}
142 * @throws IOException
143 * See {@link #preBuild}
144 */
145 public boolean enterModule(MavenBuildProxy build, MavenProject pom, BuildListener listener) throws InterruptedException, IOException {
146 return true;
147 }
148
149 /**
150 * Called when the build leaves the current {@link MavenProject}.
151 *
152 * @see #enterModule
153 */
154 public boolean leaveModule(MavenBuildProxy build, MavenProject pom, BuildListener listener) throws InterruptedException, IOException {
155 return true;
156 }
157
158 /**
159 * Called before execution of a single mojo.
160 *
161 * <p>
162 * When this method is invoked, {@link MojoInfo#mojo} is fully injected with its configuration values.
163 *
164 * @return
165 * See {@link #preBuild}
166 * @throws InterruptedException
167 * See {@link #preBuild}
168 * @throws IOException
169 * See {@link #preBuild}
170 */
171 public boolean preExecute(MavenBuildProxy build, MavenProject pom, MojoInfo mojo, BuildListener listener) throws InterruptedException, IOException {
172 return true;
173 }
174
175 /**
176 * Called after execution of a single mojo.
177 * <p>
178 * See {@link #preExecute} for the contract.
179 *
180 * @param error
181 * If mojo execution failed with {@link MojoFailureException} or
182 * {@link MojoExecutionException}, this method is still invoked
183 * with those error objects.
184 * If mojo executed successfully, this parameter is null.
185 */
186 public boolean postExecute(MavenBuildProxy build, MavenProject pom, MojoInfo mojo, BuildListener listener, Throwable error) throws InterruptedException, IOException {
187 return true;
188 }
189
190 /**
191 * Called after a build of one maven2 module is completed.
192 *
193 * <p>
194 * Note that at this point the build result is still not determined.
195 *
196 * @return
197 * See {@link #preBuild}
198 * @throws InterruptedException
199 * See {@link #preBuild}
200 * @throws IOException
201 * See {@link #preBuild}
202 */
203 public boolean postBuild(MavenBuildProxy build, MavenProject pom, BuildListener listener) throws InterruptedException, IOException {
204 return true;
205 }
206
207 /**
208 * Called after the maven execution finished and the result is determined.
209 *
210 * <p>
211 * This method fires after {@link #postBuild(MavenBuildProxy, MavenProject, BuildListener)}.
212 * Works like {@link Publisher#perform(Build, Launcher, BuildListener)}.
213 */
214 public boolean end(MavenBuild build, Launcher launcher, BuildListener listener) throws InterruptedException, IOException {
215 return true;
216 }
217
218 /**
219 * Called after a {@link MavenReport} is successfully generated.
220 *
221 * <p>
222 * {@link MavenReport} is an execution unit inside the Maven site plugin mojos,
223 * such as <tt>site:generate</tt>. These are what's configured through
224 * &lt;reporting> tag inside POM, although there's normally more
225 * {@link MavenReport}s than what's specified explicitly, due to defaulting
226 * and inheritance and all the other Maven processing.
227 *
228 * <p>
229 * This provides an opportunity for
230 * plugins to auto-perform some action when a certain reporting is generated.
231 *
232 * <p>
233 * This method is invoked during the execution of site mojos, between its
234 * {@link #preExecute(MavenBuildProxy, MavenProject, MojoInfo, BuildListener)}
235 * and {@link #postExecute(MavenBuildProxy, MavenProject, MojoInfo, BuildListener, Throwable)}
236 *
237 * @return
238 * See {@link #preBuild}
239 * @throws InterruptedException
240 * See {@link #preBuild}
241 * @throws IOException
242 * See {@link #preBuild}
243 * @since 1.237
244 */
245 public boolean reportGenerated(MavenBuildProxy build, MavenProject pom, MavenReportInfo report, BuildListener listener) throws InterruptedException, IOException {
246 return true;
247 }
248
249 /**
250 * Equivalent of {@link BuildStep#getProjectAction(AbstractProject)}
251 * for {@link MavenReporter}.
252 *
253 * <p>
254 * Registers a transient action to {@link MavenModule} when it's rendered.
255 * This is useful if you'd like to display an action at the module level.
256 *
257 * <p>
258 * Since this contributes a transient action, the returned {@link Action}
259 * will not be serialized.
260 *
261 * <p>
262 * For this method to be invoked, your {@link MavenReporter} has to invoke
263 * {@link MavenBuildProxy#registerAsProjectAction(MavenReporter)} during the build.
264 *
265 * @return
266 * null not to contribute an action, which is the default.
267 * @deprecated as of 1.341
268 * Use {@link #getProjectActions(MavenModule)} instead.
269 */
270 public Action getProjectAction(MavenModule module) {
271 return null;
272 }
273
274 /**
275 * Equivalent of {@link BuildStep#getProjectActions(AbstractProject)}
276 * for {@link MavenReporter}.
277 *
278 * <p>
279 * Registers a transient action to {@link MavenModule} when it's rendered.
280 * This is useful if you'd like to display an action at the module level.
281 *
282 * <p>
283 * Since this contributes a transient action, the returned {@link Action}
284 * will not be serialized.
285 *
286 * <p>
287 * For this method to be invoked, your {@link MavenReporter} has to invoke
288 * {@link MavenBuildProxy#registerAsProjectAction(MavenReporter)} during the build.
289 *
290 * @return
291 * can be empty but never null.
292 * @since 1.341
293 */
294 public Collection<? extends Action> getProjectActions(MavenModule module) {
295 // delegate to getProjectAction (singular) for backward compatible behavior
296 Action a = getProjectAction(module);
297 if (a==null) return Collections.emptyList();
298 return Collections.singletonList(a);
299 }
300
301 /**
302 * Works like {@link #getProjectAction(MavenModule)} but
303 * works at {@link MavenModuleSet} level.
304 *
305 * <p>
306 * For this method to be invoked, your {@link MavenReporter} has to invoke
307 * {@link MavenBuildProxy#registerAsAggregatedProjectAction(MavenReporter)} during the build.
308 *
309 * @return
310 * null not to contribute an action, which is the default.
311 */
312 public Action getAggregatedProjectAction(MavenModuleSet project) {
313 return null;
314 }
315
316 public MavenReporterDescriptor getDescriptor() {
317 return (MavenReporterDescriptor) Jenkins.getInstance().getDescriptorOrDie(getClass());
318 }
319 }
320