Package hudson.model.listeners

Class SCMListener

java.lang.Object

hudson.model.listeners.SCMListener

All Implemented Interfaces:

ExtensionPoint

public abstract class SCMListener
extends Object
implements ExtensionPoint

Receives notifications about SCM activities in Hudson.

This is an abstract class so that methods added in the future won't break existing listeners.

Once instantiated, use the register() method to start receiving events.

Since:

1.70

Author:

Kohsuke Kawaguchi

See Also:

Jenkins.getSCMListeners()

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
SCMListener()

Method Summary

Modifier and Type	Method	Description
static Collection<? extends SCMListener>	all()
void	onChangeLogParsed(AbstractBuild<?,?> build, BuildListener listener, ChangeLogSet<?> changelog)	Deprecated.
void	onChangeLogParsed(Run<?,?> build, SCM scm, TaskListener listener, ChangeLogSet<?> changelog)	Called once the changelog is determined.
void	onCheckout(Run<?,?> build, SCM scm, FilePath workspace, TaskListener listener, File changelogFile, SCMRevisionState pollingBaseline)	Should be called immediately after SCM.checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState) is called.
void	register()	Deprecated. Use Extension instead.
boolean	unregister()	Deprecated. Use Extension instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SCMListener

public SCMListener()

Method Detail

onCheckout

public void onCheckout(Run<?,?> build,
                       SCM scm,
                       FilePath workspace,
                       TaskListener listener,
                       @CheckForNull
                       File changelogFile,
                       @CheckForNull
                       SCMRevisionState pollingBaseline)
                throws Exception

Should be called immediately after SCM.checkout(Run, Launcher, FilePath, TaskListener, File, SCMRevisionState) is called.

Parameters:

pollingBaseline - information about what actually was checked out, if that is available, and this checkout is intended to be included in the build’s polling (if it does any at all)

Throws:

Exception - if the checkout should be considered failed

Since:

1.568

onChangeLogParsed

public void onChangeLogParsed(Run<?,?> build,
                              SCM scm,
                              TaskListener listener,
                              ChangeLogSet<?> changelog)
                       throws Exception

Called once the changelog is determined.

During a build, Jenkins fetches the update of the workspace from SCM, and determines the changelog (see SCM.checkout(hudson.model.Run<?, ?>, hudson.Launcher, hudson.FilePath, hudson.model.TaskListener, java.io.File, hudson.scm.SCMRevisionState)). Immediately after that, a build will invoke this method on all registered SCMListeners.

If a build failed before we successfully determine changelog, this method will not be invoked (for example, if "cvs update" failed.) OTOH, this method is invoked before the actual build (like ant invocation) happens.

This is an opportunity for SCM-related plugins to act on changelog. A typical usage includes parsing commit messages and do cross-referencing between other systems. Implementations can also contribute Action to AbstractBuild (by build.getActions().add(...) to display additional data on build views.

TODO: once we have cvsnews plugin, refer to its usage.

Parameters:

build - The build in progress, which just finished determining changelog. At this point this build is still in progress. Never null.

listener - BuildListener for on-going build. This can be used to report any errors or the general logging of what's going on. This will show up in the "console output" of the build. Never null.

changelog - Set of changes detected in this build. This is the same value returned from AbstractBuild.getChangeSet() but passed separately for convenience.

Throws:

Exception - If any exception is thrown from this method, it will be recorded and causes the build to fail.

Since:

1.568

onChangeLogParsed

@Deprecated
public void onChangeLogParsed(AbstractBuild<?,?> build,
                              BuildListener listener,
                              ChangeLogSet<?> changelog)
                       throws Exception

Deprecated.

Throws:

Exception

all

public static Collection<? extends SCMListener> all()

Since:

1.568

register

@Deprecated
public final void register()

Deprecated.

Use Extension instead.

unregister

@Deprecated
public final boolean unregister()

Deprecated.

Use Extension instead.