Package 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

  • Field Details

  • Constructor Details

    • RunListener

      protected RunListener(Class<R> targetType)

    • RunListener

      protected RunListener()

  • Method Details

    • 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.

    • allowLoad

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) public boolean allowLoad(@NonNull Job<?,?> job, int buildNumber)
      Allows listeners to veto build loading.
      Parameters:
      job - the job from which a build might be loaded
      buildNumber - the proposed build number
      Returns:
      false to veto build loading
      See Also:

    • createLoadAllower

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) public IntPredicate createLoadAllower(@NonNull Job<?,?> job)
      Allows listeners to veto build loading during startup. Same behavior as allowLoad(hudson.model.Job<?, ?>, int) but permits an implementation to more efficiently respond to numerous queries about historical build numbers.

    • 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.