File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\model\listeners\SCMListener.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.model.listeners;
25
26 import hudson.model.AbstractBuild;
27 import hudson.model.Action;
28 import hudson.model.BuildListener;
29 import jenkins.model.Jenkins;
30 import hudson.scm.ChangeLogSet;
31 import hudson.scm.SCM;
32 import hudson.ExtensionPoint;
33
34 /**
35 * Receives notifications about SCM activities in Hudson.
36 *
37 * <p>
38 * This is an abstract class so that methods added in the future won't break existing listeners.
39 *
40 * <p>
41 * Once instanciated, use the {@link #register()} method to start receiving events.
42 *
43 * @author Kohsuke Kawaguchi
44 * @see jenkins.model.Jenkins#getSCMListeners()
45 * @since 1.70
46 */
47 public abstract class SCMListener implements ExtensionPoint {
48 /**
49 * Called once the changelog is determined.
50 *
51 * <p>
52 * During a build, Jenkins fetches the update of the workspace from SCM,
53 * and determines the changelog (see {@link SCM#checkout}). Immediately
54 * after that, a build will invoke this method on all registered
55 * {@link SCMListener}s.
56 *
57 * <p>
58 * If a build failed before we successfully determine changelog, this method
59 * will not be invoked (for example, if "cvs update" failed.) OTOH, this method
60 * is invoked before the actual build (like ant invocation) happens.
61 *
62 * <p>
63 * This is an opportunity for SCM-related plugins to act on changelog.
64 * A typical usage includes parsing commit messages and do cross-referencing
65 * between other systems. Implementations can also contribute {@link Action}
66 * to {@link AbstractBuild} (by {@code build.getActions().add(...)} to
67 * display additional data on build views.
68 *
69 * <p>
70 * TODO: once we have cvsnews plugin, refer to its usage.
71 *
72 * @param build
73 * The build in progress, which just finished determining changelog.
74 * At this point this build is still in progress. Never null.
75 * @param listener
76 * {@link BuildListener} for on-going build. This can be used to report
77 * any errors or the general logging of what's going on. This will show
78 * up in the "console output" of the build. Never null.
79 * @param changelog
80 * Set of changes detected in this build. This is the same value
81 * returned from {@link AbstractBuild#getChangeSet()} but passed
82 * separately for convenience.
83 *
84 * @throws Exception
85 * If any exception is thrown from this method, it will be recorded
86 * and causes the build to fail.
87 */
88 public void onChangeLogParsed(AbstractBuild<?,?> build, BuildListener listener, ChangeLogSet<?> changelog) throws Exception {
89 }
90
91 /**
92 * Registers this {@link SCMListener} so that it will start receiving events.
93 */
94 public final void register() {
95 Jenkins.getInstance().getSCMListeners().add(this);
96 }
97
98 /**
99 * Unregisters this {@link SCMListener} so that it will never receive further events.
100 *
101 * <p>
102 * Unless {@link SCMListener} is unregistered, it will never be a subject of GC.
103 */
104 public final boolean unregister() {
105 return Jenkins.getInstance().getSCMListeners().remove(this);
106 }
107 }
108