hudson.tasks

Class BuildTrigger

java.lang.Object

hudson.tasks.BuildStepCompatibilityLayer

hudson.tasks.Publisher

hudson.tasks.Recorder

hudson.tasks.BuildTrigger

All Implemented Interfaces:

ExtensionPoint, Describable<Publisher>, BuildStep, DependencyDeclarer

public class BuildTrigger
extends Recorder
implements DependencyDeclarer

Triggers builds of other projects.

Despite what the name suggests, this class doesn't actually trigger other jobs as a part of perform(hudson.model.AbstractBuild, hudson.Launcher, hudson.model.BuildListener) method. Its main job is to simply augment DependencyGraph. Jobs are responsible for triggering downstream jobs on its own, because dependencies may come from other sources.

This class, however, does provide the execute(AbstractBuild, BuildListener, BuildTrigger) method as a convenience method to invoke downstream builds.

Its counterpart is ReverseBuildTrigger.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BuildTrigger.DescriptorImpl

Nested classes/interfaces inherited from class hudson.tasks.Publisher

Publisher.DescriptorExtensionListImpl

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Nested classes/interfaces inherited from interface hudson.tasks.BuildStep

BuildStep.PublisherList

Field Summary

Fields inherited from interface hudson.tasks.BuildStep

BUILDERS, PUBLISHERS

Constructor Summary

Constructors

Constructor and Description
BuildTrigger(Collection<? extends AbstractProject> childProjects, Result threshold)
BuildTrigger(List<AbstractProject> childProjects, Result threshold)
BuildTrigger(String childProjects, boolean evenIfUnstable)
BuildTrigger(String childProjects, Result threshold)
BuildTrigger(String childProjects, String threshold)

Method Summary

Modifier and Type	Method and Description
void	buildDependencyGraph(AbstractProject owner, DependencyGraph graph) Invoked from AbstractProject.buildDependencyGraph(DependencyGraph).
static boolean	execute(AbstractBuild build, BuildListener listener) Convenience method to trigger downstream builds.
static boolean	execute(AbstractBuild build, BuildListener listener, BuildTrigger trigger) Deprecated. since 1.341; use execute(AbstractBuild,BuildListener)
List<Job<?,?>>	getChildJobs(AbstractProject<?,?> owner)
List<AbstractProject>	getChildProjects() Deprecated. as of 1.406 Use getChildProjects(ItemGroup)
List<AbstractProject>	getChildProjects(AbstractProject owner) Deprecated. use getChildJobs(hudson.model.AbstractProject<?, ?>)
List<AbstractProject>	getChildProjects(ItemGroup base) Deprecated.
String	getChildProjectsValue()
BuildStepMonitor	getRequiredMonitorService() Declares the scope of the synchronization monitor this BuildStep expects from outside.
Result	getThreshold()
boolean	hasSame(AbstractProject owner, Collection<? extends AbstractProject> projects) Deprecated. apparently unused
boolean	hasSame(Collection<? extends AbstractProject> projects) Deprecated. as of 1.406 Use hasSame(AbstractProject, Collection)
boolean	needsToRunAfterFinalized() Return true if this Publisher needs to run after the build result is fully finalized.
boolean	onJobRenamed(String oldName, String newName) Deprecated. Does not handle folder moves.
boolean	perform(AbstractBuild build, Launcher launcher, BuildListener listener) Runs the step over the given build and reports the progress to the listener.

Methods inherited from class hudson.tasks.Recorder

getDescriptor

Methods inherited from class hudson.tasks.Publisher

all, getProjectAction, prebuild

Methods inherited from class hudson.tasks.BuildStepCompatibilityLayer

getProjectAction, getProjectActions, perform, prebuild

Methods inherited from class java.lang.Object

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

Constructor Detail

BuildTrigger

public BuildTrigger(String childProjects,
                    boolean evenIfUnstable)

BuildTrigger

@DataBoundConstructor
public BuildTrigger(String childProjects,
                                          String threshold)

BuildTrigger

public BuildTrigger(String childProjects,
                    Result threshold)

BuildTrigger

public BuildTrigger(List<AbstractProject> childProjects,
                    Result threshold)

BuildTrigger

public BuildTrigger(Collection<? extends AbstractProject> childProjects,
                    Result threshold)

Method Detail

getChildProjectsValue

public String getChildProjectsValue()

getThreshold

public Result getThreshold()

getChildProjects

@Deprecated
public List<AbstractProject> getChildProjects()

Deprecated. as of 1.406 Use getChildProjects(ItemGroup)

getChildProjects

@Deprecated
public List<AbstractProject> getChildProjects(AbstractProject owner)

Deprecated. use getChildJobs(hudson.model.AbstractProject<?, ?>)

getChildProjects

@Deprecated
public List<AbstractProject> getChildProjects(ItemGroup base)

Deprecated.

getChildJobs

@Nonnull
public List<Job<?,?>> getChildJobs(@Nonnull
                                            AbstractProject<?,?> owner)

getRequiredMonitorService

public BuildStepMonitor getRequiredMonitorService()

Description copied from interface: BuildStep

Declares the scope of the synchronization monitor this BuildStep expects from outside.

This method is introduced for preserving compatibility with plugins written for earlier versions of Hudson, which never run multiple builds of the same job in parallel. Such plugins often assume that the outcome of the previous build is completely available, which is no longer true when we do concurrent builds.

To minimize the necessary code change for such plugins, BuildStep implementations can request Hudson to externally perform synchronization before executing them. This behavior is as follows:

BuildStepMonitor.BUILD

This BuildStep is only executed after the previous build is fully completed (thus fully restoring the earlier semantics of one build at a time.)

BuildStepMonitor.STEP

This BuildStep is only executed after the same step in the previous build is completed. For build steps that use a weaker assumption and only rely on the output from the same build step of the early builds, this improves the concurrency.

BuildStepMonitor.NONE

No external synchronization is performed on this build step. This is the most efficient, and thus the recommended value for newer plugins. Wherever necessary, you can directly use CheckPoints to perform necessary synchronizations.

Migrating Older Implementation

If you are migrating BuildStep implementations written for earlier versions of Hudson, here's what you can do:

• To demand the backward compatible behavior from Jenkins, leave this method unoverridden, and make no other changes to the code. This will prevent users from reaping the benefits of concurrent builds, but at least your plugin will work correctly, and therefore this is a good easy first step.
• If your build step doesn't use anything from a previous build (for example, if you don't even call Run.getPreviousBuild()), then you can return BuildStepMonitor.NONE without making further code changes and you are done with migration.
• If your build step only depends on Actions that you added in the previous build by yourself, then you only need BuildStepMonitor.STEP scope synchronization. Return it from this method ,and you are done with migration without any further code changes.
• If your build step makes more complex assumptions, return BuildStepMonitor.NONE and use CheckPoints directly in your code. The general idea is to call CheckPoint.block() before you try to access the state from the previous build.

Specified by:

getRequiredMonitorService in interface BuildStep

hasSame

@Deprecated
public boolean hasSame(AbstractProject owner,
                                   Collection<? extends AbstractProject> projects)

Deprecated. apparently unused

hasSame

@Deprecated
public boolean hasSame(Collection<? extends AbstractProject> projects)

Deprecated. as of 1.406 Use hasSame(AbstractProject, Collection)

perform

public boolean perform(AbstractBuild build,
                       Launcher launcher,
                       BuildListener listener)

Description copied from interface: BuildStep

Runs the step over the given build and reports the progress to the listener.

A plugin can contribute the action object to Actionable.getActions() so that a 'report' becomes a part of the persisted data of Build. This is how JUnit plugin attaches the test report to a build page, for example.

When this build step needs to make (direct or indirect) permission checks to ACL (for example, to locate other projects by name, build them, or access their artifacts) then it must be run under a specific Authentication. In such a case, the implementation should check whether Jenkins.getAuthentication() is ACL.SYSTEM, and if so, replace it for the duration of this step with Jenkins.ANONYMOUS. (Either using ACL.impersonate(org.acegisecurity.Authentication), or by making explicit calls to ACL.hasPermission(Authentication, Permission).) This would typically happen when no QueueItemAuthenticator was available, configured, and active.

Specified by:

perform in interface BuildStep

Overrides:

perform in class BuildStepCompatibilityLayer

Returns:

Delegates to SimpleBuildStep.perform(Run, FilePath, Launcher, TaskListener) if possible, always returning true or throwing an error.

execute

@Deprecated
public static boolean execute(AbstractBuild build,
                                          BuildListener listener,
                                          BuildTrigger trigger)

Deprecated. since 1.341; use execute(AbstractBuild,BuildListener)

execute

public static boolean execute(AbstractBuild build,
                              BuildListener listener)

Convenience method to trigger downstream builds.

Parameters:

build - The current build. Its downstreams will be triggered.

listener - Receives the progress report.

buildDependencyGraph

public void buildDependencyGraph(AbstractProject owner,
                                 DependencyGraph graph)

Description copied from interface: DependencyDeclarer

Invoked from AbstractProject.buildDependencyGraph(DependencyGraph).

Specified by:

buildDependencyGraph in interface DependencyDeclarer

Parameters:

owner - The project that owns the publishers, builders, etc. This information is conceptually redundant, as those objects are only configured against the single owner, but this information is nevertheless passed in since often owner information is not recorded. Never null.

graph - The dependency graph being built. Never null.

needsToRunAfterFinalized

public boolean needsToRunAfterFinalized()

Description copied from class: Publisher

Return true if this Publisher needs to run after the build result is fully finalized.

The execution of normal Publishers are considered within a part of the build. This allows publishers to mark the build as a failure, or to include their execution time in the total build time.

So normally, that is the preferable behavior, but in a few cases this is problematic. One of such cases is when a publisher needs to trigger other builds, which in turn need to see this build as a completed build. Those plugins that need to do this can return true from this method, so that the BuildStepCompatibilityLayer.perform(AbstractBuild, Launcher, BuildListener) method is called after the build is marked as completed.

When Publisher behaves this way, note that they can no longer change the build status anymore.

Overrides:

needsToRunAfterFinalized in class Publisher

onJobRenamed

@Deprecated
public boolean onJobRenamed(String oldName,
                                        String newName)

Deprecated. Does not handle folder moves.