KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > hudson > model > listeners > SCMListener


1 package hudson.model.listeners;
2
3 import hudson.model.AbstractBuild;
4 import hudson.model.Action;
5 import hudson.model.BuildListener;
6 import hudson.model.Hudson;
7 import hudson.scm.ChangeLogSet;
8 import hudson.scm.SCM;
9 import hudson.ExtensionPoint;
10
11 /**
12  * Receives notifications about SCM activities in Hudson.
13  *
14  * <p>
15  * This is an abstract class so that methods added in the future won't break existing listeners.
16  *
17  * <p>
18  * Once instanciated, use the {@link #register()} method to start receiving events.
19  *
20  * @author Kohsuke Kawaguchi
21  * @see Hudson#getSCMListeners()
22  * @since 1.70
23  */
24 public abstract class SCMListener implements ExtensionPoint {
25     /**
26      * Called once the changelog is determined.
27      *
28      * <p>
29      * During a build, Hudson fetches the update of the workspace from SCM,
30      * and determines the changelog (see {@link SCM#checkout}). Immediately
31      * after that, a build will invoke this method on all registered
32      * {@link SCMListener}s.
33      *
34      * <p>
35      * If a build failed before we successfully determine changelog, this method
36      * will not be invoked (for example, if "cvs update" failed.) OTOH, this method
37      * is invoked before the actual build (like ant invocation) happens.
38      *
39      * <p>
40      * This is an opportunity for SCM-related plugins to act on changelog.
41      * A typical usage includes parsing commit messages and do cross-referencing
42      * between other systems. Implementations can also contribute {@link Action}
43      * to {@link AbstractBuild} (by {@code build.getActions().add(...)} to
44      * display additional data on build views.
45      *
46      * <p>
47      * TODO: once we have cvsnews plugin, refer to its usage.
48      *
49      * @param build
50      * The build in progress, which just finished determining changelog.
51      * At this point this build is still in progress. Never null.
52      * @param listener
53      * {@link BuildListener} for on-going build. This can be used to report
54      * any errors or the general logging of what's going on. This will show
55      * up in the "console output" of the build. Never null.
56      * @param changelog
57      * Set of changes detected in this build. This is the same value
58      * returned from {@link AbstractBuild#getChangeSet()} but passed
59      * separately for convenience.
60      *
61      * @throws Exception
62      * If any exception is thrown from this method, it will be recorded
63      * and causes the build to fail.
64      */
65     public void onChangeLogParsed(AbstractBuild<?,?> build, BuildListener listener, ChangeLogSet<?> changelog) throws Exception JavaDoc {
66     }
67
68     /**
69      * Registers this {@link SCMListener} so that it will start receiving events.
70      */
71     public final void register() {
72         Hudson.getInstance().getSCMListeners().add(this);
73     }
74
75     /**
76      * Unregisters this {@link SCMListener} so that it will never receive further events.
77      *
78      * <p>
79      * Unless {@link SCMListener} is unregistered, it will never be a subject of GC.
80      */
81     public final boolean unregister() {
82         return Hudson.getInstance().getSCMListeners().remove(this);
83     }
84 }
85
Popular Tags