hudson.model.listeners

Class RunListener<R extends Run>

java.lang.Object

hudson.model.listeners.RunListener<R>

All Implemented Interfaces:

ExtensionPoint

Direct Known Subclasses:

GlobalBuildDiscarderListener, PeepholePermalink.RunListenerImpl, ReverseBuildTrigger.RunListenerImpl

public abstract class RunListener<R extends Run>
extends Object
implements ExtensionPoint

Receives notifications about builds.

Listener is always Hudson-wide, so once registered it gets notifications for every build that happens in this Hudson.

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

Since:

1.145

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
static CopyOnWriteList<RunListener>	LISTENERS Deprecated. as of 1.281 Use all() for read access, and use Extension for registration.
Class<R>	targetType

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RunListener()
protected	RunListener(Class<R> targetType)

Method Summary

Modifier and Type	Method and Description
static ExtensionList<RunListener>	all() Returns all the registered RunListeners.
static void	fireCompleted(Run r, TaskListener listener) Fires the onCompleted(Run, TaskListener) event.
static void	fireDeleted(Run r) Fires the onDeleted(R) event.
static void	fireFinalized(Run r) Fires the onFinalized(Run) event.
static void	fireInitialize(Run r) Fires the onInitialize(Run) event.
static void	fireStarted(Run r, TaskListener listener) Fires the onStarted(Run, TaskListener) event.
void	onCompleted(R r, TaskListener listener) Called after a build is completed.
void	onDeleted(R r) Called right before a build is going to be deleted.
void	onFinalized(R r) Called after a build is moved to the Run.State.COMPLETED state.
void	onInitialize(R r) Called when a Run is entering execution.
void	onStarted(R r, TaskListener listener) Called when a build is started (i.e.
void	register() Deprecated. as of 1.281 Put Extension on your class to get it auto-registered.
Environment	setUpEnvironment(AbstractBuild build, Launcher launcher, BuildListener listener) Runs before the SCM.checkout(AbstractBuild, Launcher, FilePath, BuildListener, File) runs, and performs a set up.
void	unregister() Reverse operation of register().

Methods inherited from class java.lang.Object

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

Field Detail

targetType

public final Class<R extends Run> targetType

LISTENERS

@Deprecated
public static final CopyOnWriteList<RunListener> LISTENERS

Deprecated. as of 1.281 Use all() for read access, and use Extension for registration.

List of registered listeners.

Constructor Detail

RunListener

protected RunListener(Class<R> targetType)

RunListener

protected RunListener()

Method Detail

onCompleted

public void onCompleted(R r,
                        @NonNull
                        TaskListener listener)

Called after a build is completed.

Parameters:

r - The completed build.

listener - The listener for this build. This can be used to produce log messages, for example, which becomes a part of the "console output" of this build. But when this method runs, the build is considered completed, so its status cannot be changed anymore.

Throws:

RuntimeException - Any exception/error thrown from this method will be swallowed to prevent broken listeners from breaking all the builds.

onFinalized

public void onFinalized(R r)

Called after a build is moved to the Run.State.COMPLETED state.

At this point, all the records related to a build is written down to the disk. As such, TaskListener is no longer available. This happens later than onCompleted(Run, TaskListener).

Throws:

RuntimeException - Any exception/error thrown from this method will be swallowed to prevent broken listeners from breaking all the builds.

onInitialize

public void onInitialize(R r)

Called when a Run is entering execution.

Parameters:

r - The started build.

Since:

2.9

onStarted

public void onStarted(R r,
                      TaskListener listener)

Called when a build is started (i.e. it was in the queue, and will now start running on an executor)

Parameters:

r - The started build.

listener - The listener for this build. This can be used to produce log messages, for example, which becomes a part of the "console output" of this build.

Throws:

RuntimeException - Any exception/error thrown from this method will be swallowed to prevent broken listeners from breaking all the builds.

setUpEnvironment

public Environment setUpEnvironment(AbstractBuild build,
                                    Launcher launcher,
                                    BuildListener listener)
                             throws IOException,
                                    InterruptedException,
                                    Run.RunnerAbortedException

Runs before the SCM.checkout(AbstractBuild, Launcher, FilePath, BuildListener, File) runs, and performs a set up. Can contribute additional properties/env vars to the environment.

A typical strategy is for implementations to check JobPropertys and other configuration of the project to determine the environment to inject, which allows you to achieve the equivalent of BuildWrapper, but without UI.

Parameters:

build - The build in progress for which an Environment object is created. Never null.

launcher - This launcher can be used to launch processes for this build. If the build runs remotely, launcher will also run a job on that remote machine. Never null.

listener - Can be used to send any message.

Returns:

non-null if the build can continue, null if there was an error and the build needs to be aborted.

Throws:

IOException - terminates the build abnormally. Hudson will handle the exception and reports a nice error message.

Run.RunnerAbortedException - If a fatal error is detected and the callee handled it gracefully, throw this exception to suppress a stack trace by the receiver.

InterruptedException

Since:

1.410

onDeleted

public void onDeleted(R r)

Called right before a build is going to be deleted.

Parameters:

r - The build.

Throws:

RuntimeException - Any exception/error thrown from this method will be swallowed to prevent broken listeners from breaking all the builds.

register

@Deprecated
public void register()

Deprecated. as of 1.281 Put Extension on your class to get it auto-registered.

Registers this object as an active listener so that it can start getting callbacks invoked.

unregister

public void unregister()

Reverse operation of register().

fireCompleted

public static void fireCompleted(Run r,
                                 @NonNull
                                 TaskListener listener)

Fires the onCompleted(Run, TaskListener) event.

fireInitialize

public static void fireInitialize(Run r)

Fires the onInitialize(Run) event.

fireStarted

public static void fireStarted(Run r,
                               TaskListener listener)

Fires the onStarted(Run, TaskListener) event.

fireFinalized

public static void fireFinalized(Run r)

Fires the onFinalized(Run) event.

fireDeleted

public static void fireDeleted(Run r)

Fires the onDeleted(R) event.

all

public static ExtensionList<RunListener> all()

Returns all the registered RunListeners.