jetbrains.buildServer.serverSide
Interface BuildPromotion

All Superinterfaces:
java.lang.Comparable<BuildPromotion>

public interface BuildPromotion
extends java.lang.Comparable<BuildPromotion>

Contains information necessary to reproduce a build. A build receives build promotion when it added to queue.


Method Summary
 SQueuedBuild addToQueue(SBuildAgent buildAgent, java.lang.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(java.lang.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.
 java.util.List<? extends BuildPromotion> getAllDependencies()
          Returns the full list of snapshot dependencies (including transitive ones) of this build promotion filtered according to current user permissions.
 java.util.List<SArtifactDependency> getArtifactDependencies()
          Returns collection of artifact dependencies to be sent to an agent.
 SBuild getAssociatedBuild()
          Returns running or finished build associated with this promotion or null if there is no such build.
 java.lang.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 promotion
 java.util.Map<java.lang.String,java.lang.String> getBuildParameters()
          Returns combined map of default and custom defined build parameters.
 SBuildType getBuildType()
          Returns build configuration to which this promotion corresponds.
 java.lang.String getBuildTypeExternalId()
          Returns the external id of the associated build type.
 java.lang.String getBuildTypeId()
          Returns internal id of build configuration to which this promotion corresponds, same as getBuildType().getBuildTypeId()
 java.util.Collection<SBuildAgent> getCanRunOnAgents(java.util.Collection<SBuildAgent> available)
          Returns collection of agents where this build promotion can be executed.
 java.util.List<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 policy
 java.util.Map<SBuildAgent,CompatibilityResult> getCompatibilityMap(java.util.Collection<SBuildAgent> available)
          Returns compatibility map for given set of agents.
 java.util.List<SVcsModification> getContainingChanges()
          Returns changes containing in this promotion.
 java.util.Map<java.lang.String,java.lang.String> getCustomParameters()
          Returns map of user-defined build and configuration parameters associated with this build promotion.
 java.util.Map<java.lang.String,java.lang.String> getDefaultParameters()
          Returns map of default build and configuration parameters associated with this build promotion.
 java.util.Collection<? extends BuildDependency> getDependedOnMe()
          Returns snapshot dependencies of parent build promotions depending on this promotion.
 java.util.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.
 java.lang.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.
 java.util.Map<java.lang.String,java.lang.String> getParameters()
          Returns combined map of default and custom parameters.
 SBuildType getParentBuildType()
          Returns base build configuration to which this promotion corresponds, i.e.
 java.lang.String getParentBuildTypeId()
          For non personal builds returns same as getBuildTypeId().
 java.util.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.
 SQueuedBuild getQueuedBuild()
          Returns queued build associated with this promotion or null if there is no such build in the queue
 java.util.List<BuildRevision> getRevisions()
          Returns VCS root revisions associated with this promotion.
 java.util.List<VcsRootInstanceEntry> getVcsRootEntries()
          Returns VCS root entries associated with this promotion.
 boolean isCanceled()
          Return true if associated build is canceled
 boolean isChangesDetached()
           
 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 build
 boolean isUsed()
          Returns true if there is a reference to this build promotion from queued, running or history build.
 void setBuildComment(User user, java.lang.String comment)
          Assigns the build comment for this promotion
 
Methods inherited from interface java.lang.Comparable
compareTo
 

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 the correspondent build configuration is deleted - returns null.

Returns:
the correspondent build configuration or null if that was deleted.

getBuildTypeId

@NotNull
java.lang.String getBuildTypeId()
Returns internal id of build configuration to which this promotion corresponds, same as getBuildType().getBuildTypeId()

Returns:
id of build configuration

getBuildTypeExternalId

@NotNull
java.lang.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.

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
java.lang.String getParentBuildTypeId()
For non personal builds returns same as getBuildTypeId(). For personal builds returns id of parent build configuration: getParentBuildType().getBuildTypeId()

Returns:
see above

getRevisions

@NotNull
java.util.List<BuildRevision> getRevisions()
Returns VCS root revisions associated with this promotion.

Returns:
VCS root revisions

getVcsRootEntries

@NotNull
java.util.List<VcsRootInstanceEntry> getVcsRootEntries()
Returns VCS root entries associated with this promotion.

Returns:
VCS root entries

getContainingChanges

@NotNull
java.util.List<SVcsModification> getContainingChanges()
Returns changes containing in this promotion. Ordering: last detected modifications goes first in the list

Returns:
see above

getPersonalChanges

@NotNull
java.util.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
java.util.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 - policy
returnChangesIfNoPreviousBuild - whether to return changes if there is no previous build in the history.
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
java.lang.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
java.lang.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
                     java.lang.String comment)
Assigns the build comment for this promotion

Parameters:
user - user who sets the comment
comment - 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
java.util.Map<java.lang.String,java.lang.String> getCustomParameters()
Returns map of user-defined build and configuration parameters associated with this build promotion.

Returns:
see above
Since:
6.5

getDefaultParameters

@NotNull
java.util.Map<java.lang.String,java.lang.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
java.util.Map<java.lang.String,java.lang.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, see ParametersPreprocessor for more details.

Returns:
see above
Since:
6.5

getBuildParameters

@NotNull
java.util.Map<java.lang.String,java.lang.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, see ParametersPreprocessor for more details.

Returns:
see above

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
java.util.Collection<? extends BuildDependency> getDependencies()
Returns the direct snapshot dependencies of this build promotion filtered according to current user permissions.

Returns:
see above

getAllDependencies

@NotNull
java.util.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
java.util.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.

Returns:
see above

addToQueue

@Nullable
SQueuedBuild addToQueue(@NotNull
                                 java.lang.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 also TriggeredByBuilder
Returns:
the queued build or null if adding to queue is impossible for some reason

addToQueue

@Nullable
SQueuedBuild addToQueue(@NotNull
                                 SBuildAgent buildAgent,
                                 @NotNull
                                 java.lang.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 run
triggeredBy - contains details about who triggered build, see also TriggeredByBuilder
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
java.util.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
java.util.Collection<SBuildAgent> getCanRunOnAgents(@NotNull
                                                            java.util.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
java.util.Map<SBuildAgent,CompatibilityResult> getCompatibilityMap(@NotNull
                                                                           java.util.Collection<SBuildAgent> available)
Returns compatibility map for given set of agents.

Returns:
see above
Since:
7.1.2

getBranch

@Nullable
Branch getBranch()
Returns:
branch associated with this build promotion if it exists and null otherwise.
Since:
7.1