Package jetbrains.buildServer.serverSide
Interface BuildPromotion
-
- All Superinterfaces:
Comparable<BuildPromotion>
- All Known Subinterfaces:
BuildPromotionEx
- All Known Implementing Classes:
AbstractBuildPromotion
,BuildPromotionImpl
,BuildPromotionManagerImpl.TemplateDummyBuildPromotion
,DummyBuildPromotion
,MockBuildPromotion
public interface BuildPromotion extends Comparable<BuildPromotion>
Contains information necessary to reproduce a build. A build receives build promotion when it added to queue.
-
-
Field Summary
Fields Modifier and Type Field Description static String
NOT_EXISTING_BUILD_TYPE_ID
A stub value that is returned bygetBuildTypeExternalId()
when build type external id does not exist.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description SQueuedBuild
addToQueue(String triggeredBy)
Creates a new build on the base of this promotion (and all necessary builds for the promotions this one depends on) and adds it to the Queue.SQueuedBuild
addToQueue(SBuildAgent buildAgent, String triggeredBy)
Creates a new build on the base of this promotion (and all necessary builds for the promotions this one depends on) and adds it to the Queue.BuildPromotion
copy(boolean copyRevisions)
Creates copy of this build promotion (a copy will have different id).BuildPromotion[]
findTops()
Return a collection of top-level build promotions for sequence builds this build promotion participates in.List<? extends BuildPromotion>
getAllDependencies()
Returns the full list of snapshot dependencies (including transitive ones) of this build promotion filtered according to current user permissions.List<SArtifactDependency>
getArtifactDependencies()
Returns collection of artifact dependencies to be sent to an agent.File
getArtifactsDirectory()
SBuild
getAssociatedBuild()
Returns running or finished build associated with this promotion or null if there is no such build.Long
getAssociatedBuildId()
Returns id of the build associated with this promotion, or null if there is no such build.Branch
getBranch()
Comment
getBuildComment()
Returns build comment assigned for this promotionCollection<SBuildFeatureDescriptor>
getBuildFeaturesOfType(String featureType)
Returns settings of the enabled build features of the specified type.BuildLog
getBuildLog()
Map<String,String>
getBuildParameters()
Returns combined map of default and custom defined build parameters.ReadOnlyBuildSettings
getBuildSettings()
Returns settings specified toBuildPromotionEx.freezeSettings(BuildTypeEx, String)
method or settings of this buildType this promotion belongs to ifBuildPromotionEx.freezeSettings(BuildTypeEx, String)
wasn't calledSBuildType
getBuildType()
Returns build configuration to which this promotion corresponds.String
getBuildTypeExternalId()
Returns the external id of the associated build type.String
getBuildTypeId()
Returns internal id of build configuration to which this promotion corresponds, same asgetBuildType()
.getBuildTypeId()Collection<SBuildAgent>
getCanRunOnAgents(Collection<SBuildAgent> available)
Returns collection of agents where this build promotion can be executed.BuildChanges
getChanges(ChangesCalculationOptions options)
Returns build changes according to the specified optionsList<SVcsModification>
getChanges(SelectPrevBuildPolicy policy, boolean returnChangesIfNoPreviousBuild)
Returns changes containing in this promotion according to the specified policy.UserSet<SUser>
getCommitters(SelectPrevBuildPolicy selectPrevBuildPolicy)
Returns committers of this build selected according to specified policyMap<SBuildAgent,CompatibilityResult>
getCompatibilityMap(Collection<SBuildAgent> available)
Returns compatibility map for given set of agents.Collection<SBuildAgent>
getCompatibleAgents(Collection<SBuildAgent> available)
Returns compatible agents only, does not check that build configuration is allowed to be executed on the agentsList<SVcsModification>
getContainingChanges()
Returns changes containing in this promotion.String
getCreatorNodeId()
Map<String,String>
getCustomParameters()
Returns map of user-defined build and configuration parameters associated with this build promotion.Map<String,String>
getDefaultParameters()
Returns map of default build and configuration parameters associated with this build promotion.Collection<? extends BuildDependency>
getDependedOnMe()
Returns snapshot dependencies of parent build promotions depending on this promotion.Collection<? extends BuildDependency>
getDependencies()
Returns the direct snapshot dependencies of this build promotion filtered according to current user permissions.long
getId()
Returns id of this promotion, promotion id is unique among all other build promotions and is not changed during promotion life cycle.Long
getLastModificationId()
Returns id of the last change associated with this promotion or null if changes collecting is not performed yet.int
getNumberOfDependedOnMe()
Returns total number of parent snapshot dependencies (without permissions filtering).int
getNumberOfDependencies()
Returns total number of snapshot dependencies (without permissions filtering).SUser
getOwner()
For personal builds returns owner of the build.Map<String,String>
getParameters()
Returns combined map of default and custom parameters.String
getParameterValue(String paramName)
SBuildType
getParentBuildType()
Returns base build configuration to which this promotion corresponds, i.e.String
getParentBuildTypeId()
For non personal builds returns same asgetBuildTypeId()
.List<SVcsModification>
getPersonalChanges()
Returns personal changes associated with this build promotion.BuildPromotion
getPreviousBuildPromotion(SelectPrevBuildPolicy policy)
Returns previous promotion created before this one and corresponding to the specified policy.List<String>
getPrivateTags(SUser user)
Returns list of private tag labels in lexicographical order for particular user for this build promotionString
getProjectExternalId()
Returns the project external idString
getProjectId()
Returns the project internal id.SQueuedBuild
getQueuedBuild()
Returns queued build associated with this promotion or null if there is no such build in the queueDate
getQueuedDate()
Returns the date when the build was added to queue.List<BuildRevision>
getRevisions()
Returns VCS root revisions associated with this promotion.Date
getServerStartDate()
Returns the timestamp when the build was removed from the queue.Collection<TagData>
getTagDatas()
Returns list of all tags for this build promotion, no special order is preservedList<String>
getTags()
Returns list of public tag labels in lexicographical order for the build promotionList<VcsRootInstanceEntry>
getVcsRootEntries()
Returns VCS root entries associated with this promotion.boolean
hasBuildFeatureOfType(String featureType)
Returns true if this build promotion has a build feature of the specified typeboolean
isCanceled()
Return true if associated build is canceledboolean
isChangesDetached()
boolean
isCompositeBuild()
boolean
isEquivalentTo(BuildPromotion promotion)
Returns true if this build promotion is equivalent to specified promotion, i.e.boolean
isFailedToCollectChanges()
boolean
isLaterThan(BuildPromotion promotion)
Returns true if this promotion contains more recent changes comparing to the specified promotion.boolean
isOutOfChangesSequence()
Returns true if there is a build started before this build promotion associated build which contains more recent changes.boolean
isPartOfBuildChain()
boolean
isPersonal()
Return true if this build promotion relates to personal buildboolean
isUsed()
Returns true if there is a reference to this build promotion from queued, running or history build.void
setBuildComment(User user, String comment)
Assigns the build comment for this promotionvoid
setDesiredBranchName(String branchName)
void
setPrivateTags(List<String> labels, SUser user)
Set private tags for particular user Attention! Replace all private tags related to the particular user with new setvoid
setTagDatas(Collection<TagData> tags)
Changes tag set for this build promotion.void
setTags(List<String> labels)
Set public tags.-
Methods inherited from interface java.lang.Comparable
compareTo
-
-
-
-
Field Detail
-
NOT_EXISTING_BUILD_TYPE_ID
static final String NOT_EXISTING_BUILD_TYPE_ID
A stub value that is returned bygetBuildTypeExternalId()
when build type external id does not exist. The value is deliberately invalid in terms of external id rules to avoid a possibility of clash.- See Also:
- Constant Field Values
-
-
Method Detail
-
getId
long getId()
Returns id of this promotion, promotion id is unique among all other build promotions and is not changed during promotion life cycle.- Returns:
- id of this build promotion
-
getOwner
@Nullable SUser getOwner()
For personal builds returns owner of the build. For non personal builds returns null.- Returns:
- see above
- Since:
- 4.5
-
getBuildType
@Nullable SBuildType getBuildType()
Returns build configuration to which this promotion corresponds. If promotion is for personal build, returns RemoteBuildType.If the correspondent build configuration is deleted - returns null.
- Returns:
- the correspondent build configuration or null if that was deleted.
-
getBuildTypeId
@NotNull String getBuildTypeId()
Returns internal id of build configuration to which this promotion corresponds, same asgetBuildType()
.getBuildTypeId()- Returns:
- id of build configuration
-
getBuildTypeExternalId
@NotNull String getBuildTypeExternalId()
Returns the external id of the associated build type. In case of the personal build - it is the identifier of the real build configuration (as for a regular build), without suffixes.If the external identifier does not exist (this might happen for a running build if the build type was deleted, and a new build type with same external id was created), a
NOT_EXISTING_BUILD_TYPE_ID
value is returned.- Returns:
- the external identifier of the associated build type.
- Since:
- 8.0
-
getParentBuildType
@Nullable SBuildType getParentBuildType()
Returns base build configuration to which this promotion corresponds, i.e. for personal builds returns parent build configuration, not the personal build type- Returns:
- see above
-
getParentBuildTypeId
@NotNull String getParentBuildTypeId()
For non personal builds returns same asgetBuildTypeId()
. For personal builds returns id of parent build configuration: getParentBuildType().getBuildTypeId()- Returns:
- see above
-
getProjectId
@Nullable String getProjectId()
Returns the project internal id.- Returns:
- project internal id
- Since:
- 2017.1.2
-
getProjectExternalId
@Nullable String getProjectExternalId()
Returns the project external id- Returns:
- project external id
- Since:
- 2017.1.2
-
getRevisions
@NotNull List<BuildRevision> getRevisions()
Returns VCS root revisions associated with this promotion.- Returns:
- VCS root revisions
-
getVcsRootEntries
@NotNull List<VcsRootInstanceEntry> getVcsRootEntries()
Returns VCS root entries associated with this promotion.- Returns:
- VCS root entries
-
getContainingChanges
@NotNull List<SVcsModification> getContainingChanges()
Returns changes containing in this promotion. Result is the same as for BuildPromotionEx#getDetectedChanges((SelectPrevBuildPolicy.SINCE_LAST_BUILD, false).stream() .map(ChangeDescriptor::getRelatedVcsChange).filter(Objects::nonNull).collect(Collectors.toList()); Ordering: last detected modifications goes first in the list- Returns:
- see above
-
getPersonalChanges
@NotNull List<SVcsModification> getPersonalChanges()
Returns personal changes associated with this build promotion. If promotion is not personal (isPersonal == false), returns empty collection.- Returns:
- see above
- Since:
- 6.5
-
getChanges
@NotNull List<SVcsModification> getChanges(@NotNull SelectPrevBuildPolicy policy, boolean returnChangesIfNoPreviousBuild)
Returns changes containing in this promotion according to the specified policy. Ordering: last detected modifications goes first in the list- Parameters:
policy
- policyreturnChangesIfNoPreviousBuild
- whether to return changes if there is no previous build in the history.- Returns:
- see above
-
getChanges
@NotNull BuildChanges getChanges(@NotNull ChangesCalculationOptions options)
Returns build changes according to the specified options- Parameters:
options
- changes calculation options- Returns:
- see above
-
getCommitters
UserSet<SUser> getCommitters(@NotNull SelectPrevBuildPolicy selectPrevBuildPolicy)
Returns committers of this build selected according to specified policy- Parameters:
selectPrevBuildPolicy
- policy- Returns:
- see above
- Since:
- 4.5
-
getLastModificationId
@Nullable Long getLastModificationId()
Returns id of the last change associated with this promotion or null if changes collecting is not performed yet. Returns -1 if changes collecting is performed but there were no changes detected and there were no changes in the build configuration since its creation.- Returns:
- see above
-
isPersonal
boolean isPersonal()
Return true if this build promotion relates to personal build- Returns:
- see above
-
getAssociatedBuild
@Nullable SBuild getAssociatedBuild()
Returns running or finished build associated with this promotion or null if there is no such build.- Returns:
- see above
-
getAssociatedBuildId
@Nullable Long getAssociatedBuildId()
Returns id of the build associated with this promotion, or null if there is no such build.- Returns:
- see above
-
getQueuedBuild
@Nullable SQueuedBuild getQueuedBuild()
Returns queued build associated with this promotion or null if there is no such build in the queue- Returns:
- see above
-
getBuildComment
@Nullable Comment getBuildComment()
Returns build comment assigned for this promotion- Returns:
- build comment
- Since:
- 5.1
-
setBuildComment
void setBuildComment(@NotNull User user, @Nullable String comment)
Assigns the build comment for this promotion- Parameters:
user
- user who sets the commentcomment
- text of the comment- Since:
- 5.1
-
isLaterThan
boolean isLaterThan(@NotNull BuildPromotion promotion)
Returns true if this promotion contains more recent changes comparing to the specified promotion.- Parameters:
promotion
- promotion- Returns:
- see above
-
getCustomParameters
@NotNull Map<String,String> getCustomParameters()
Returns map of user-defined build and configuration parameters associated with this build promotion.- Returns:
- see above
- Since:
- 6.5
-
getDefaultParameters
@NotNull Map<String,String> getDefaultParameters()
Returns map of default build and configuration parameters associated with this build promotion. Default parameters are taken from the build configuration when build promotion is created.- Returns:
- see above
- Since:
- 6.5
-
getParameters
@NotNull Map<String,String> getParameters()
Returns combined map of default and custom parameters. Combined map contains both build and configuration parameters. Custom parameters take precedence over default parameters. Note that parameters returned by this method can be modified before they are passed to agent, seeParametersPreprocessor
for more details.- Returns:
- see above
- Since:
- 6.5
-
getParameterValue
@Nullable String getParameterValue(@NotNull String paramName)
- Parameters:
paramName
- parameter name- Returns:
- value of the parameter with given name or null if there is no such parameter
- Since:
- 9.1.2
-
getBuildParameters
@NotNull Map<String,String> getBuildParameters()
Returns combined map of default and custom defined build parameters. Custom build parameters takes precedence over default parameters. Note that parameters returned by this method can be modified before they are passed to agent, seeParametersPreprocessor
for more details.- Returns:
- see above
-
getBuildSettings
@NotNull ReadOnlyBuildSettings getBuildSettings() throws BuildTypeNotFoundException
Returns settings specified toBuildPromotionEx.freezeSettings(BuildTypeEx, String)
method or settings of this buildType this promotion belongs to ifBuildPromotionEx.freezeSettings(BuildTypeEx, String)
wasn't called- Throws:
BuildTypeNotFoundException
- if build type not exist anymore- Since:
- 2022.12
-
isEquivalentTo
boolean isEquivalentTo(@NotNull BuildPromotion promotion)
Returns true if this build promotion is equivalent to specified promotion, i.e. it corresponds to the same build configuration, contains same revisions and build parameters.- Parameters:
promotion
- build promotion- Returns:
- see above
-
getDependencies
@NotNull Collection<? extends BuildDependency> getDependencies()
Returns the direct snapshot dependencies of this build promotion filtered according to current user permissions.- Returns:
- see above
-
getAllDependencies
@NotNull List<? extends BuildPromotion> getAllDependencies()
Returns the full list of snapshot dependencies (including transitive ones) of this build promotion filtered according to current user permissions. Dependencies are returned "bottom-up", i.e. direct dependencies go to the end of the list.- Returns:
- see above
-
getNumberOfDependencies
int getNumberOfDependencies()
Returns total number of snapshot dependencies (without permissions filtering).- Returns:
- see above
-
getDependedOnMe
@NotNull Collection<? extends BuildDependency> getDependedOnMe()
Returns snapshot dependencies of parent build promotions depending on this promotion. Parent build promotions are filtered according to current user permissions.- Returns:
- see above
-
getNumberOfDependedOnMe
int getNumberOfDependedOnMe()
Returns total number of parent snapshot dependencies (without permissions filtering).- Returns:
- see above
-
findTops
BuildPromotion[] findTops()
Return a collection of top-level build promotions for sequence builds this build promotion participates in. This build promotion may have several tops only if it has an associated running or finished build. If this build promotion is a top of the graph, returns an array with itself as the only element. This method always returns at least one element. The array of build promotions is sorted in a way that the most recent top of the graph is returned first.- Returns:
- see above
-
addToQueue
@Nullable SQueuedBuild addToQueue(@NotNull String triggeredBy)
Creates a new build on the base of this promotion (and all necessary builds for the promotions this one depends on) and adds it to the Queue.- Parameters:
triggeredBy
- contains details about who triggered build, see alsoTriggeredByBuilder
- Returns:
- the queued build or null if adding to queue is impossible for some reason
-
addToQueue
@Nullable SQueuedBuild addToQueue(@NotNull SBuildAgent buildAgent, @NotNull String triggeredBy)
Creates a new build on the base of this promotion (and all necessary builds for the promotions this one depends on) and adds it to the Queue.- Parameters:
buildAgent
- build agent where the build is to runtriggeredBy
- contains details about who triggered build, see alsoTriggeredByBuilder
- Returns:
- the queued build or null if adding to queue is impossible for some reason
-
getPreviousBuildPromotion
@Nullable BuildPromotion getPreviousBuildPromotion(@NotNull SelectPrevBuildPolicy policy)
Returns previous promotion created before this one and corresponding to the specified policy.- Parameters:
policy
- policy- Returns:
- see above
-
isUsed
boolean isUsed()
Returns true if there is a reference to this build promotion from queued, running or history build.- Returns:
- see above
-
copy
BuildPromotion copy(boolean copyRevisions)
Creates copy of this build promotion (a copy will have different id). Note that this method does not make a deep copy if dependencies exist.- Parameters:
copyRevisions
- indicates whether to copy revisions associated with this promotion or not- Returns:
- copy of this build promotion
-
isOutOfChangesSequence
boolean isOutOfChangesSequence()
Returns true if there is a build started before this build promotion associated build which contains more recent changes.- Returns:
- see above
-
isChangesDetached
boolean isChangesDetached()
- Returns:
- true if changes are detached from this promotion, i.e. next build will have all of the changes included in this promotion.
- Since:
- 7.0
-
isPartOfBuildChain
boolean isPartOfBuildChain()
- Returns:
- true if this build promotion is a part of build dependencies graph, i.e. there are promotions having dependencies on this promotion or this promotion has dependencies on other promotions.
-
isCanceled
boolean isCanceled()
Return true if associated build is canceled- Returns:
- see above
-
isFailedToCollectChanges
boolean isFailedToCollectChanges()
- Returns:
- true if process of changes collecting failed for this build
- Since:
- 7.0
-
getArtifactDependencies
@NotNull List<SArtifactDependency> getArtifactDependencies()
Returns collection of artifact dependencies to be sent to an agent. This collection may or may not be the same as default build configuration dependencies because before sending to an agent revision rules are fixed (dependencies begin pointing to concrete builds).- Returns:
- see above
- Since:
- 5.0
-
getCanRunOnAgents
@NotNull Collection<SBuildAgent> getCanRunOnAgents(@NotNull Collection<SBuildAgent> available)
Returns collection of agents where this build promotion can be executed. Returned agents are compatible with this build promotion, and build promotion build configuration is allowed to be executed on these agents.- Returns:
- see above
- Since:
- 7.1
-
getCompatibilityMap
@NotNull Map<SBuildAgent,CompatibilityResult> getCompatibilityMap(@NotNull Collection<SBuildAgent> available)
Returns compatibility map for given set of agents. Note: can return empty map if the current build promotion is marked for deletion or its build configuration no longer exists.- Returns:
- see above
- Since:
- 7.1.2
-
getCompatibleAgents
@NotNull Collection<SBuildAgent> getCompatibleAgents(@NotNull Collection<SBuildAgent> available)
Returns compatible agents only, does not check that build configuration is allowed to be executed on the agents- Returns:
- see above
- Since:
- 9.1
-
getBranch
@Nullable Branch getBranch()
- Returns:
- branch associated with this build promotion if it exists and null otherwise.
- Since:
- 7.1
-
getBuildLog
@NotNull BuildLog getBuildLog()
- Returns:
- Log for operations which could occur before build start, like changes collecting or logging detailed triggering information.
- Since:
- 9.0
-
getArtifactsDirectory
@NotNull File getArtifactsDirectory() throws BuildTypeNotFoundException
- Returns:
- Artifacts directory for given build promotion
- Throws:
BuildTypeNotFoundException
- in some rare cases when path to the artifacts directory is not known to this build promotion and there is no build configuration anymore so it is not possible to find this location without performing expensive disk scan operations- Since:
- 9.0
- See Also:
SBuildType.getArtifactsDirectory()
,SBuild.getArtifactsDirectory()
-
setTagDatas
void setTagDatas(@NotNull Collection<TagData> tags)
Changes tag set for this build promotion. Attention! The whole set of tags will be replaced with new one. It means that even if new set contains only public tag the action will affect private tags as well.- Parameters:
tags
- tags- Since:
- 9.0
- See Also:
TagDataUtil
,for variety of tag-releated actions
-
getTagDatas
@NotNull Collection<TagData> getTagDatas()
Returns list of all tags for this build promotion, no special order is preserved- Returns:
- tags
- Since:
- 9.0
- See Also:
TagDataUtil
,for variety of tag-releated actions
-
getPrivateTags
@NotNull List<String> getPrivateTags(@NotNull SUser user)
Returns list of private tag labels in lexicographical order for particular user for this build promotion- Returns:
- tags
- Since:
- 9.0
-
setPrivateTags
void setPrivateTags(@Nullable List<String> labels, @NotNull SUser user)
Set private tags for particular user Attention! Replace all private tags related to the particular user with new set- Parameters:
labels
- new tag labelsuser
- a particular user which tags should be updated- See Also:
for variety of tag-releated actions
-
getTags
@NotNull List<String> getTags()
Returns list of public tag labels in lexicographical order for the build promotion- Returns:
- tags
- Since:
- 9.0
-
setTags
void setTags(List<String> labels)
Set public tags. Attention! Replace old public tags set with new one.- Parameters:
labels
- tag labels- See Also:
for variety of tag-releated actions
-
getQueuedDate
@Nullable Date getQueuedDate()
Returns the date when the build was added to queue.- Returns:
- queued time, null if promotion wasn't queued
- Since:
- 9.0
-
getServerStartDate
@Nullable Date getServerStartDate()
Returns the timestamp when the build was removed from the queue.- Returns:
- the timestamp when the build was removed from the queue, null if wasn't yet
- Since:
- 9.0
-
setDesiredBranchName
void setDesiredBranchName(@NotNull String branchName) throws IllegalArgumentException
- Throws:
IllegalArgumentException
-
isCompositeBuild
boolean isCompositeBuild()
- Returns:
- true if build promotion has dependencies and it was created in a build configuration marked as composite build
- Since:
- 2017.2
-
getCreatorNodeId
@NotNull String getCreatorNodeId()
- Returns:
- node id which created the build promotion.
- Since:
- 2020.1
-
hasBuildFeatureOfType
boolean hasBuildFeatureOfType(@NotNull String featureType)
Returns true if this build promotion has a build feature of the specified type- Parameters:
featureType
- the type of the build feature- Returns:
- true if the build promotion has the build feature in its settings and false otherwise
- Since:
- 2024.12
-
getBuildFeaturesOfType
@NotNull Collection<SBuildFeatureDescriptor> getBuildFeaturesOfType(@NotNull String featureType)
Returns settings of the enabled build features of the specified type. If the settings have parameter references, then they won't be resolved (see alsoSBuild.getBuildFeaturesOfType(String)
). This method returns the same result asgetBuildSettings().getBuildFeaturesOfType(String)
.- Parameters:
featureType
- the type of the build feature- Returns:
- the settings of the build features of the specified type or empty list if there are no such build features
- Since:
- 2024.12
-
-