Package hudson.plugins.promoted_builds

Class PromotionProcess

java.lang.Object

hudson.model.AbstractModelObject

hudson.model.Actionable

hudson.model.AbstractItem

hudson.model.Job<P,R>

hudson.model.AbstractProject<PromotionProcess,Promotion>

hudson.plugins.promoted_builds.PromotionProcess

All Implemented Interfaces:

ExtensionPoint, BuildableItem, BuildableItemWithBuildWrappers, Describable<PromotionProcess>, DescriptorByNameOwner, Item, ModelObject, PersistenceRoot, SubTask, Queue.Task, ResourceActivity, Saveable, SearchableModelObject, SearchItem, AccessControlled, LazyBuildMixIn.LazyLoadingJob<PromotionProcess,Promotion>, Loadable, ModelObjectWithChildren, ModelObjectWithContextMenu, ParameterizedJobMixIn.ParameterizedJob<PromotionProcess,Promotion>, TriggeredItem, OnMaster, HasWidgets, org.kohsuke.stapler.HttpDeletable, org.kohsuke.stapler.StaplerOverridable, org.kohsuke.stapler.StaplerProxy

public final class PromotionProcess
extends AbstractProject<PromotionProcess,Promotion>
implements Saveable, Describable<PromotionProcess>, BuildableItemWithBuildWrappers

A dummy AbstractProject to carry out promotion operations.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PromotionProcess.DescriptorImpl

Nested classes/interfaces inherited from class hudson.model.AbstractProject

AbstractProject.AbstractProjectDescriptor, AbstractProject.BecauseOfBuildInProgress, AbstractProject.BecauseOfDownstreamBuildInProgress, AbstractProject.BecauseOfUpstreamBuildInProgress, AbstractProject.LabelValidator

Nested classes/interfaces inherited from class hudson.model.Job

Job.LastItemListener, Job.SubItemBuildsLocationImpl

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Nested classes/interfaces inherited from interface org.kohsuke.stapler.HttpDeletable

org.kohsuke.stapler.HttpDeletable.HttpDeletableDispatcher

Nested classes/interfaces inherited from interface jenkins.model.ModelObjectWithContextMenu

ModelObjectWithContextMenu.ContextMenu, ModelObjectWithContextMenu.ContextMenuVisibility, ModelObjectWithContextMenu.MenuItem, ModelObjectWithContextMenu.MenuItemType

Field Summary

Fields

Modifier and Type	Field	Description
String	assignedLabel	The label that promotion process can be run on.
final DescribableList<PromotionCondition,PromotionConditionDescriptor>	conditions	PromotionConditions.
String	icon	The icon that represents this promotion process.
String	isVisible	Tells if this promotion should be hidden.

Fields inherited from class hudson.model.AbstractProject

ABORT, blockBuildWhenDownstreamBuilding, blockBuildWhenUpstreamBuilding, BUILD_NOW_TEXT, builds, disabled, transientActions, triggers

Fields inherited from class hudson.model.Job

HISTORY_ADAPTER, nextBuildNumber, properties, runIdMigrator

Fields inherited from class hudson.model.AbstractItem

description, displayName, name, PRONOUN, SKIP_PERMISSION_CHECK, TASK_NOUN

Fields inherited from interface hudson.model.Item

BUILD, CANCEL, CONFIGURE, CREATE, DELETE, DISCOVER, EXTENDED_READ, PERMISSIONS, READ, WIPEOUT, WORKSPACE

Fields inherited from interface hudson.model.Saveable

NOOP

Method Summary

Modifier and Type	Method	Description
PermalinkProjectAction.Permalink	asPermalink()
AbstractProject<?,?>	asProject()
protected void	buildDependencyGraph(DependencyGraph graph)
boolean	considerPromotion(AbstractBuild<?,?> build)	Deprecated. Use considerPromotion2(AbstractBuild)
Future<Promotion>	considerPromotion2(AbstractBuild<?,?> build)	Checks if the build is promotable, and if so, promote it.
Future<Promotion>	considerPromotion2(AbstractBuild<?,?> build, ManualCondition.ManualApproval approval)
Future<Promotion>	considerPromotion2(AbstractBuild<?,?> build, List<ParameterValue> params)
void	doBuild(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, TimeDuration delay)
void	doSetName(String name)
static PromotionProcess	fromJson(org.kohsuke.stapler.StaplerRequest2 req, net.sf.json.JSONObject o)	Creates unconnected PromotionProcess instance from the JSON configuration.
ACL	getACL()
static List<Descriptor<? extends BuildStep>>	getAll()
Label	getAssignedLabel()
String	getAssignedLabelString()	Gets the textual representation of the assigned label as it was entered by the user.
protected Class<Promotion>	getBuildClass()
List<BuildStep>	getBuildSteps()
Map<Descriptor<BuildWrapper>,BuildWrapper>	getBuildWrappers()
DescribableList<BuildWrapper,Descriptor<BuildWrapper>>	getBuildWrappersList()
String	getCustomWorkspace()	Gets the customWorkspace of the owner project.
PromotionProcess.DescriptorImpl	getDescriptor()
String	getIcon()	Get the icon name, without the extension.
String	getIsVisible()
JDK	getJDK()
List<PromotionBadge>	getMetQualifications(AbstractBuild<?,?> build)	Get the badges of conditions that were passed for this promotion for the build
AbstractProject<?,?>	getOwner()	Gets the owner AbstractProject that configured JobPropertyImpl as a job property.
JobPropertyImpl	getParent()
PromotionCondition	getPromotionCondition(String promotionClassName)	Get the promotion condition by referencing it fully qualified class name
DescribableList<Publisher,Descriptor<Publisher>>	getPublishersList()
AbstractProject	getRootProject()	Returns the root project value.
String	getShortUrl()
List<PromotionCondition>	getUnmetConditions(AbstractBuild<?,?> build)	Get the conditions that have not been met for this promotion for the build
boolean	isActive()
boolean	isFingerprintConfigured()
boolean	isInQueue(AbstractBuild<?,?> build)
Status	isMet(AbstractBuild<?,?> build)	Checks if all the conditions to promote a build is met.
boolean	isVisible()
void	promote(AbstractBuild<?,?> build, Cause cause, PromotionBadge... badges)
void	promote(AbstractBuild<?,?> build, Cause cause, Status qualification)	Deprecated. Use promote2(AbstractBuild, Cause, Status)
Future<Promotion>	promote2(AbstractBuild<?,?> build, Cause cause, Status qualification)	Promote the given build by using the given qualification.
Future<Promotion>	promote2(AbstractBuild<?,?> build, Cause cause, Status qualification, List<ParameterValue> params)	Promote the given build by using the given qualification.
boolean	scheduleBuild()	Deprecated. You need to be using scheduleBuild(AbstractBuild)
boolean	scheduleBuild(AbstractBuild<?,?> build)
boolean	scheduleBuild(AbstractBuild<?,?> build, Cause cause)	Deprecated. Use scheduleBuild2(AbstractBuild, Cause)
Future<Promotion>	scheduleBuild2(AbstractBuild<?,?> build, Cause cause)
Future<Promotion>	scheduleBuild2(AbstractBuild<?,?> build, Cause cause, List<ParameterValue> params)	Schedules the promotion.
boolean	supportsMakeDisabled()	JENKINS-27716: Since 1.585, the promotion must explicitly indicate that it can be disabled.

Methods inherited from class hudson.model.AbstractProject

_getRuns, addProperty, addToList, addTrigger, blockBuildWhenDownstreamBuilding, blockBuildWhenUpstreamBuilding, buildDescribable, buildDescribable, checkAbortPermission, checkout, createExecutable, createTransientActions, disable, doBuild, doBuildWithParameters, doCheckRetryCount, doConfigSubmit, doDoWipeOutWorkspace, doPolling, doWs, enable, findNearest, findNearest, getActions, getAuthToken, getBuild, getBuildByNumber, getBuildingDownstream, getBuildingUpstream, getBuildNowText, getBuildTriggerUpstreamProjects, getCauseOfBlockage, getDelay, getDownstreamProjects, getDownstreamProjectsForApi, getEnvironment, getEstimatedDurationCandidates, getFirstBuild, getHasCustomQuietPeriod, getIconColor, getLastBuild, getLastBuiltOn, getLazyBuildMixIn, getModuleRoot, getModuleRoots, getNearestBuild, getNearestOldBuild, getProminentActions, getPronoun, getQueueItem, getQuietPeriod, getRelationship, getRelevantLabels, getResourceActivities, getResourceList, getSameNodeConstraint, getScm, getScmCheckoutRetryCount, getScmCheckoutStrategy, getSomeBuildWithWorkspace, getSomeWorkspace, getSubTasks, getTransitiveDownstreamProjects, getTransitiveUpstreamProjects, getTrigger, getTriggers, getUpstreamProjects, getUpstreamProjectsForApi, getWorkspace, getWorkspaceResource, hasAbortPermission, hasCustomScmCheckoutRetryCount, hasParticipant, isBuildable, isConcurrentBuild, isConfigurable, isDisabled, isInQueue, loadBuild, makeSearchIndex, newBuild, onCreatedFromScratch, onLoad, performDelete, poll, pollSCMChanges, removeFromList, removeRun, removeTrigger, resolveForCLI, save, scheduleBuild, scheduleBuild2, scheduleBuild2, scheduleBuild2, scheduleBuild2, scheduleBuild2, schedulePolling, setAssignedLabel, setAssignedNode, setBlockBuildWhenDownstreamBuilding, setBlockBuildWhenUpstreamBuilding, setConcurrentBuild, setCustomWorkspace, setDisabled, setJDK, setQuietPeriod, setScm, setScmCheckoutStrategy, submit, submit, triggers, updateTransientActions

Methods inherited from class hudson.model.Job

assignBuildNumber, checkRename, createHistoryWidget, delete, doBuildStatus, doChildrenContextMenu, doChildrenContextMenu, doDescription, doDoRename, doRssAll, doRssChangelog, doRssFailed, fastUpdateNextBuildNumber, getAllJobs, getAllProperties, getBuildDir, getBuildDiscarder, getBuildForCLI, getBuildHealth, getBuildHealthReports, getBuilds, getBuilds, getBuildsAsMap, getBuildsByTimestamp, getBuildStatusIconClassName, getBuildStatusUrl, getBuildTimeGraph, getCharacteristicEnvVars, getDynamic, getDynamic, getEstimatedDuration, getLastBuildsOverThreshold, getLastCompletedBuild, getLastFailedBuild, getLastStableBuild, getLastSuccessfulBuild, getLastUnstableBuild, getLastUnsuccessfulBuild, getLogRotator, getNewBuilds, getNextBuildNumber, getOverrides, getPermalinks, getProperties, getProperty, getProperty, getTimeline, isBuilding, isHoldOffBuildUntilSave, isKeepDependencies, isLogUpdated, isNameEditable, logRotate, movedTo, onCopiedFrom, removeProperty, removeProperty, renameTo, saveNextBuildNumber, setBuildDiscarder, setLogRotator, supportsLogRotator, updateNextBuildNumber

Methods inherited from class hudson.model.AbstractItem

delete, delete, doCheckNewName, doConfigDotXml, doConfigDotXml, doConfirmRename, doDoDelete, doDoDelete, doReload, doSubmitDescription, doSubmitDescription, getAbsoluteUrl, getApi, getConfigFile, getDescription, getDisplayName, getDisplayNameOrNull, getFullDisplayName, getFullName, getName, getRelativeDisplayNameFrom, getRelativeNameFromGroup, getRootDir, getSearchName, getSearchUrl, getTarget, getTaskNoun, getUrl, load, setDescription, setDisplayName, setDisplayNameOrNull, toString, updateByXml, updateByXml, writeConfigDotXml, writeReplace

Methods inherited from class hudson.model.Actionable

addAction, addOrReplaceAction, doContextMenu, doContextMenu, getAction, getAction, getActions, getAllActions, removeAction, removeActions, replaceAction, replaceActions

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

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

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, hasAnyPermission, hasPermission, hasPermission, hasPermission2

Methods inherited from interface hudson.model.BuildableItem

scheduleBuild

Methods inherited from interface hudson.model.DescriptorByNameOwner

getDescriptorByName

Methods inherited from interface jenkins.widgets.HasWidgets

getWidget, getWidgets

Methods inherited from interface hudson.model.Item

delete, getAbsoluteUrl, getAllJobs, getDisplayName, getFullDisplayName, getFullName, getName, getRelativeNameFrom, getRelativeNameFrom, getUrl, onCopiedFrom, onCreatedFromScratch, onLoad, save

Methods inherited from interface jenkins.model.ParameterizedJobMixIn.ParameterizedJob

doBuild, doBuildWithParameters, doBuildWithParameters, doCancelQueue, doDisable, doEnable, getParameterizedJobMixIn, isParameterized, makeDisabled, scheduleBuild, scheduleBuild

Methods inherited from interface hudson.model.PersistenceRoot

getRootDir

Methods inherited from interface hudson.model.Queue.Task

checkAbortPermission, getAffinityKey, getCauseOfBlockage, getDefaultAuthentication, getDefaultAuthentication, getDefaultAuthentication2, getDefaultAuthentication2, getFullDisplayName, getName, getSubTasks, getUrl, getWhyBlocked, hasAbortPermission, isBuildBlocked, isConcurrentBuild

Methods inherited from interface hudson.model.ResourceActivity

getDisplayName, getResourceList

Methods inherited from interface hudson.search.SearchableModelObject

getSearch

Methods inherited from interface hudson.search.SearchItem

getSearchIndex, getSearchName, getSearchUrl

Methods inherited from interface hudson.model.queue.SubTask

getEstimatedDuration, getLastBuiltOn, getOwnerExecutable, getOwnerTask, getSameNodeConstraint

Field Details

conditions

public final DescribableList<PromotionCondition,PromotionConditionDescriptor> conditions

PromotionConditions. All have to be met for a build to be promoted.

icon

public String icon

The icon that represents this promotion process. This is the name of the SVG icon that can be found in ${rootURL}/plugin/promoted-builds/icons/, e.g. "star-gold".

assignedLabel

public String assignedLabel

The label that promotion process can be run on.

isVisible

public String isVisible

Tells if this promotion should be hidden.

Method Details

fromJson

public static PromotionProcess fromJson(org.kohsuke.stapler.StaplerRequest2 req,
 net.sf.json.JSONObject o)
                                 throws Descriptor.FormException,
IOException

Creates unconnected PromotionProcess instance from the JSON configuration. This is mostly only useful for capturing its configuration in XML format.

Parameters:

req - Request

o - JSON object with source data

Returns:

Parsed promotion process

Throws:

Descriptor.FormException - form submission issue, includes form validation

IOException - PromotionProcess creation issue

doSetName

public void doSetName(String name)

Overrides:

doSetName in class AbstractItem

getRootProject

public AbstractProject getRootProject()

Returns the root project value.

Overrides:

getRootProject in class AbstractProject<PromotionProcess,Promotion>

Returns:

the root project value.

getParent

public JobPropertyImpl getParent()

Specified by:

getParent in interface Item

Overrides:

getParent in class AbstractItem

getOwner

public AbstractProject<?,?> getOwner()

Gets the owner AbstractProject that configured JobPropertyImpl as a job property.

Returns:

Current owner project

getACL

public ACL getACL()

Specified by:

getACL in interface AccessControlled

Overrides:

getACL in class Job<PromotionProcess,Promotion>

supportsMakeDisabled

public boolean supportsMakeDisabled()

JENKINS-27716: Since 1.585, the promotion must explicitly indicate that it can be disabled. Otherwise, promotions which trigger automatically upon build completion will execute, even if they're archived.

Specified by:

supportsMakeDisabled in interface ParameterizedJobMixIn.ParameterizedJob<PromotionProcess,Promotion>

Overrides:

supportsMakeDisabled in class AbstractProject<PromotionProcess,Promotion>

getPromotionCondition

@CheckForNull
public PromotionCondition getPromotionCondition(String promotionClassName)

Get the promotion condition by referencing it fully qualified class name

Parameters:

promotionClassName - Class name of Promotion

Returns:

Promotion condition if exists

getPublishersList

public DescribableList<Publisher,Descriptor<Publisher>> getPublishersList()

Specified by:

getPublishersList in class AbstractProject<PromotionProcess,Promotion>

asProject

public AbstractProject<?,?> asProject()

Specified by:

asProject in interface BuildableItemWithBuildWrappers

getBuildWrappers

public Map<Descriptor<BuildWrapper>,BuildWrapper> getBuildWrappers()

getBuildWrappersList

public DescribableList<BuildWrapper,Descriptor<BuildWrapper>> getBuildWrappersList()

Specified by:

getBuildWrappersList in interface BuildableItemWithBuildWrappers

getBuildClass

protected Class<Promotion> getBuildClass()

Specified by:

getBuildClass in class AbstractProject<PromotionProcess,Promotion>

getBuildSteps

public List<BuildStep> getBuildSteps()

getAssignedLabelString

public String getAssignedLabelString()

Gets the textual representation of the assigned label as it was entered by the user.

Overrides:

getAssignedLabelString in class AbstractProject<PromotionProcess,Promotion>

Returns:

Assigned label string

getAssignedLabel

public Label getAssignedLabel()

Specified by:

getAssignedLabel in interface SubTask

Overrides:

getAssignedLabel in class AbstractProject<PromotionProcess,Promotion>

getJDK

public JDK getJDK()

Overrides:

getJDK in class AbstractProject<PromotionProcess,Promotion>

getCustomWorkspace

@CheckForNull
public String getCustomWorkspace()

Gets the customWorkspace of the owner project. Support for FreeStyleProject only.

Overrides:

getCustomWorkspace in class AbstractProject<PromotionProcess,Promotion>

Returns:

customWorkspace

getIcon

public String getIcon()

Get the icon name, without the extension. It will always return a non null and non empty string, as "star-gold" is used for compatibility for older promotions configurations.

Returns:

the icon name

getIsVisible

public String getIsVisible()

isVisible

public boolean isVisible()

getMetQualifications

@NonNull
public List<PromotionBadge> getMetQualifications(AbstractBuild<?,?> build)

Get the badges of conditions that were passed for this promotion for the build

Parameters:

build - The build to be checked

Returns:

List of generated promotion badges

getUnmetConditions

@NonNull
public List<PromotionCondition> getUnmetConditions(AbstractBuild<?,?> build)

Get the conditions that have not been met for this promotion for the build

Parameters:

build - Build to be checked

Returns:

List of unmet promotion conditions

isMet

@CheckForNull
public Status isMet(AbstractBuild<?,?> build)

Checks if all the conditions to promote a build is met.

Parameters:

build - Build to be checked

Returns:

null if promotion conditions are not met. otherwise returns a list of badges that record how the promotion happened.

considerPromotion

@Deprecated
public boolean considerPromotion(AbstractBuild<?,?> build)
                          throws IOException

Deprecated.

Use considerPromotion2(AbstractBuild)

Throws:

IOException

considerPromotion2

@CheckForNull
public Future<Promotion> considerPromotion2(AbstractBuild<?,?> build)
                                     throws IOException

Checks if the build is promotable, and if so, promote it.

Parameters:

build - Build to be promoted

Returns:

null if the build was not promoted, otherwise Future that kicks in when the build is completed.

Throws:

IOException

considerPromotion2

@CheckForNull
public Future<Promotion> considerPromotion2(AbstractBuild<?,?> build,
 List<ParameterValue> params)
                                     throws IOException

Throws:

IOException

promote

public void promote(AbstractBuild<?,?> build,
 Cause cause,
 PromotionBadge... badges)
             throws IOException

Throws:

IOException

promote

@Deprecated
public void promote(AbstractBuild<?,?> build,
 Cause cause,
 Status qualification)
             throws IOException

Deprecated.

Use promote2(AbstractBuild, Cause, Status)

Throws:

IOException

promote2

public Future<Promotion> promote2(AbstractBuild<?,?> build,
 Cause cause,
 Status qualification)
                           throws IOException

Promote the given build by using the given qualification.

Parameters:

build - Build to promote

cause - Why the build is promoted?

qualification - Initial promotion status

Returns:

Future to track the completion of the promotion.

Throws:

IOException - Promotion failure

promote2

public Future<Promotion> promote2(AbstractBuild<?,?> build,
 Cause cause,
 Status qualification,
 List<ParameterValue> params)
                           throws IOException

Promote the given build by using the given qualification.

Parameters:

build - Build to promote

cause - Why the build is promoted?

qualification - Initial promotion status

params - Promotion parameters

Returns:

Future to track the completion of the promotion.

Throws:

IOException - Promotion failure

scheduleBuild

@Deprecated
public boolean scheduleBuild()

Deprecated.

You need to be using scheduleBuild(AbstractBuild)

Specified by:

scheduleBuild in interface BuildableItem

scheduleBuild

public boolean scheduleBuild(@NonNull
 AbstractBuild<?,?> build)

scheduleBuild

@Deprecated
public boolean scheduleBuild(@NonNull
 AbstractBuild<?,?> build,
 @NonNull
 Cause cause)

Deprecated.

Use scheduleBuild2(AbstractBuild, Cause)

Parameters:

build - Target build

cause - Promotion cause

Returns:

true if scheduling is successful

scheduleBuild2

@CheckForNull
public Future<Promotion> scheduleBuild2(@NonNull
 AbstractBuild<?,?> build,
 Cause cause,
 @CheckForNull
 List<ParameterValue> params)

Schedules the promotion.

Parameters:

build - Target build

cause - Promotion cause

params - Parameters to be passed

Returns:

Future result or null if the promotion cannot be scheduled

doBuild

public void doBuild(org.kohsuke.stapler.StaplerRequest2 req,
 org.kohsuke.stapler.StaplerResponse2 rsp,
 @QueryParameter
 TimeDuration delay)
             throws IOException,
jakarta.servlet.ServletException

Specified by:

doBuild in interface ParameterizedJobMixIn.ParameterizedJob<PromotionProcess,Promotion>

Throws:

IOException

jakarta.servlet.ServletException

scheduleBuild2

public Future<Promotion> scheduleBuild2(@NonNull
 AbstractBuild<?,?> build,
 @NonNull
 Cause cause)

isInQueue

public boolean isInQueue(@NonNull
 AbstractBuild<?,?> build)

isFingerprintConfigured

public boolean isFingerprintConfigured()

Specified by:

isFingerprintConfigured in class AbstractProject<PromotionProcess,Promotion>

buildDependencyGraph

protected void buildDependencyGraph(DependencyGraph graph)

Overrides:

buildDependencyGraph in class AbstractProject<PromotionProcess,Promotion>

getAll

public static List<Descriptor<? extends BuildStep>> getAll()

asPermalink

public PermalinkProjectAction.Permalink asPermalink()

getDescriptor

public PromotionProcess.DescriptorImpl getDescriptor()

Specified by:

getDescriptor in interface Describable<PromotionProcess>

getShortUrl

public String getShortUrl()

Specified by:

getShortUrl in interface Item

Overrides:

getShortUrl in class AbstractItem

isActive

public boolean isActive()

considerPromotion2

public Future<Promotion> considerPromotion2(AbstractBuild<?,?> build,
 ManualCondition.ManualApproval approval)
                                     throws IOException

Throws:

IOException