Package jetbrains.buildServer.serverSide

Interface BuildPromotionEx

    • Method Detail

      • findTops

        BuildPromotionEx[] findTops()
        Description copied from interface: BuildPromotion
        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.
        Specified by:
        findTops in interface BuildPromotion
        Returns:
        see above

      • traverseDependedOnMe

        void traverseDependedOnMe​(@NotNull
                          DependencyConsumer<BuildPromotionEx> consumer)
        Traverses all build promotions depending on this one transitively. If processor returns false, traversing stops.
        Parameters:
        consumer -
        Since:
        2018.1.3

      • traverseDependencies

        void traverseDependencies​(@NotNull
                          DependencyConsumer<BuildPromotionEx> consumer)
        Traverses all build promotion dependencies (breadth first). If processor returns false, traversing stops.
        Parameters:
        consumer -
        Since:
        2018.1.3

      • findSelfOrDependencyWithProblem

        @Nullable
BuildPromotionEx findSelfOrDependencyWithProblem​(@NotNull
                                                 Predicate<BuildProblemData> predicate)
        Traverses build problems of the current build promotion and all of its dependencies using breadth first search and returns the first one for which the supplied predicate returns true
        Parameters:
        predicate - predicate to apply
        Returns:
        found dependency or null
        Since:
        2024.07

      • setBuildRevisions

        void setBuildRevisions​(@NotNull
                       Collection<BuildRevisionEx> revisions,
                       long maxModificationId,
                       long chainModificationId,
                       boolean validateBranch)
        Sets revisions and modificationId into this build promotion. If revisions list is empty, that means that changes were not collected for this build
        Parameters:
        revisions - list of revisions for this build. If empty, changes were not collected for the build (possibly, because of some failure)
        maxModificationId - modification id associated with this build, used to determine changes in this build
        chainModificationId - max mod id associated with this build configuration or its dependencies transitively, cannot be smaller than maxModificationId
        validateBranch - if set to true then branch validation logic is enabled; the validation will check whether the current build branch exists in any of the VCS roots in the provided revisions, and if it does not then a build problem will be added to the build
        Since:
        2023.11
        See Also:
        BuildPromotion.getRevisions(), BuildPromotion.getLastModificationId()

      • resetBuildRevisions

        void resetBuildRevisions()

      • getChainModificationId

        @Nullable
Long getChainModificationId()
        Returns max modification id (max result of #getLastModificationId()) among this promotion all all its dependencies transitively. Returns null if changes are not collected for this promotion yet or if this is an old promotion created before the chain modification id was introduced. Returns -1 if changes collecting was performed but there were no changes detected and there were no changes in this build configuration and its dependencies since their creation.
        Returns:
        see above

      • getPersonalChangeId

        Long getPersonalChangeId()
        Returns personal change id associated with this build promotion. If promotion is not personal (isPersonal == false), returns null.
        Returns:
        see above
        Since:
        2019.2

      • hasCustomPatch

        boolean hasCustomPatch()
        Returns:
        true if this build promotion has a custom patch associated with it which should be applied when build starts on an agent
        Since:
        2021.1

      • getCustomParametersCollection

        @NotNull
Collection<Parameter> getCustomParametersCollection()
        Returns a collection of user-defined build and configuration parameters associated with this build promotion.
        Returns:
        see above
        Since:
        2023.05

      • setCustomParameters

        void setCustomParameters​(@NotNull
                         Map<String,​String> parameters)
        Sets custom parameters in build promotion. Custom parameters contain both configuration and build parameters. Custom parameters override default parameters. BuildPromotion.persist() method should be called to persist them.
        Parameters:
        parameters - custom parameters
        Since:
        6.5

      • setCustomParameters

        void setCustomParameters​(@NotNull
                         Collection<Parameter> parameters)
        Same as #setCustomParameters(List) but accepting Parameter instances
        Since:
        2021.1

      • setAssociatedBuild

        void setAssociatedBuild​(@Nullable
                        SBuild build)
        Associates new build to this build promotion

      • removeDependency

        void removeDependency​(@NotNull
                      BuildPromotionEx promo)
        Removes dependency on specified promotion
        Parameters:
        promo -

      • replaceDependency

        void replaceDependency​(@NotNull
                       BuildPromotionEx origDependency,
                       @NotNull
                       BuildPromotionEx newDependency,
                       @NotNull
                       DependencyOptions newOptions)
        Replaces dependency on one promotion with dependency to another promotion
        Parameters:
        origDependency - original promotion
        newDependency - replacement

      • getBuildType

        @Nullable
BuildTypeEx getBuildType()
        Description copied from interface: BuildPromotion
        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.

        Specified by:
        getBuildType in interface BuildPromotion
        Returns:
        the correspondent build configuration or null if that was deleted.

      • getParentBuildType

        @Nullable
BuildTypeEx getParentBuildType()
        Description copied from interface: BuildPromotion
        Returns base build configuration to which this promotion corresponds, i.e. for personal builds returns parent build configuration, not the personal build type
        Specified by:
        getParentBuildType in interface BuildPromotion
        Returns:
        see above

      • getParametersProvider

        @NotNull
ParametersProvider getParametersProvider()
        Creates and returns a parameters provider, that provides with all parameters of this build and buidls this one depends on.

      • hasDependencyOn

        boolean hasDependencyOn​(long id)

      • getDependedOnMe

        @NotNull
Collection<BuildDependencyEx> getDependedOnMe()
        Description copied from interface: BuildPromotion
        Returns snapshot dependencies of parent build promotions depending on this promotion. Parent build promotions are filtered according to current user permissions.
        Specified by:
        getDependedOnMe in interface BuildPromotion
        Returns:
        see above

      • getDependencyGraph

        @NotNull
BuildDependencyGraph getDependencyGraph()
        Returns dependency graph as if this build promotion is the top of the graph. See also findTops()
        Returns:
        graph with this promotion at the top

      • getTopDependencyGraph

        @NotNull
TopBuildDependencyGraph getTopDependencyGraph()
        Returns topmost dependency graph
        Returns:
        see above

      • isChangeCollectingNeeded

        boolean isChangeCollectingNeeded()
        Return true if change collection is required for this build promotion (otherwise, changes are collected already).
        Returns:
        see above

      • isChangeCollectingNeeded

        boolean isChangeCollectingNeeded​(boolean checkDependencies)
        Parameters:
        checkDependencies -
        Returns:
        same as isChangeCollectingNeeded() but can also check dependencies

      • markIncomplete

        void markIncomplete()
        Mark build promotion as incomplete (canceled)

      • markAsIncompleteIfHasFailedToStartProblems

        void markAsIncompleteIfHasFailedToStartProblems()
        Marks build promotion as incomplete if it has failed to start build problems

      • isIncomplete

        boolean isIncomplete()
        Returns whether the build promotion is incomplete (canceled). Method is efficient enough, can be called often.
        Returns:
        true iff is incomplete

      • markDeleted

        void markDeleted()
          throws IllegalStateException
        Mark this promotion as deleted in the database. This makes this promotion 'invisible' for most queries, and it becomes a subject for cleanup. If there is an associated finishedBuild with this promotion, this finished build is considered deleted as well, i.e. various 'buildDeleted' events are sent.
        Throws:
        IllegalStateException - if this promotion is associated with a build

      • isDeleted

        boolean isDeleted()
        Returns:
        true if promotion is marked as deleted

      • isPersisted

        boolean isPersisted()
        Returns:
        true if this promotion was ever persisted into the database, so the method will return true even if markDeleted() was called for this promotion and promotion was previously stored in database
        Since:
        2019.1

      • hasStartedParent

        boolean hasStartedParent()
        Returns true if there exists started build which has reference to this promotion
        Returns:
        see above

      • persist

        void persist()
        Persists state of the build promotion

      • copy

        BuildPromotionEx copy​(boolean copyRevisions)
        Description copied from interface: BuildPromotion
        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.
        Specified by:
        copy in interface BuildPromotion
        Parameters:
        copyRevisions - indicates whether to copy revisions associated with this promotion or not
        Returns:
        copy of this build promotion

      • getStartedEquivalentPromotions

        @NotNull
List<BuildPromotionEx> getStartedEquivalentPromotions​(int maxNumToProcess)
        Returns build promotions with associated builds and equivalent to this build promotion (same settings, changes and revisions)
        Parameters:
        maxNumToProcess - maximum number of promotions to process while searching for equivalent promotions, -1 means unlimited
        Returns:
        see above

      • getEquivalentPromotions

        @NotNull
List<BuildPromotionEx> getEquivalentPromotions​(@NotNull
                                               List<BuildPromotionEx> queuedBuilds)
        Returns build promotions from the build queue equivalent to this build promotion (same settings, changes and revisions)
        Returns:
        see above
        Since:
        2023.11

      • isChangesCollectingInProgress

        boolean isChangesCollectingInProgress()

      • lockDependenciesOptimizing

        void lockDependenciesOptimizing()

      • unlockDependenciesOptimizing

        void unlockDependenciesOptimizing()

      • addDependedOnMe

        void addDependedOnMe​(@NotNull
                     BuildPromotionEx promoEx,
                     @NotNull
                     DependencyOptions options)
        Adds link to parent promotion
        Parameters:
        promoEx -

      • addDependedOnMeIfCached

        void addDependedOnMeIfCached​(@NotNull
                             BuildPromotionEx promotion,
                             @NotNull
                             DependencyOptions options)
        Adds link to parent promotion only if depended on me list is already loaded from DB for this promotion
        Since:
        2021.2

      • removeDependedOnMe

        void removeDependedOnMe​(@NotNull
                        BuildPromotion promoEx)
        Removes link to parent promotion
        Parameters:
        promoEx -

      • getQueuedBuild

        QueuedBuildEx getQueuedBuild()
        Description copied from interface: BuildPromotion
        Returns queued build associated with this promotion or null if there is no such build in the queue
        Specified by:
        getQueuedBuild in interface BuildPromotion
        Returns:
        see above

      • getCollectChangesError

        @Nullable
String getCollectChangesError()

      • setFailedToCollectChanges

        void setFailedToCollectChanges​(@Nullable
                               Throwable t)

      • setFinalArtifactDependencies

        void setFinalArtifactDependencies​(@NotNull
                                  List<SArtifactDependency> dependencies)
        Sets the final artifact dependencies, i.e. those which must be sent to an agent.
        Parameters:
        dependencies - the artifact dependencies
        Since:
        5.0

      • setCustomArtifactDependencies

        void setCustomArtifactDependencies​(@NotNull
                                   List<SArtifactDependency> dependencies)
        Sets custom artifact dependencies, those which override default (specified in build configuration). Custom artifact dependencies will override default completely. If list is empty, it will reset custom artifact dependencies.
        Parameters:
        dependencies - custom dependencies
        Since:
        5.0

      • getOverridenVcsRoots

        @NotNull
Map<VcsRootInstance,​VcsRootInstance> getOverridenVcsRoots()
        Get overriden vcs root map in this promotion.
        Returns:
        map from original vcs root id to substitution root id
        Since:
        6.5

      • setAttribute

        void setAttribute​(@NotNull
                  String name,
                  @Nullable
                  Object value)
        Sets some attribute to the build promotion
        Parameters:
        name - attribute name
        value - attribute value

      • getAttributes

        @NotNull
Map<String,​Object> getAttributes()
        Returns:
        map of arbitrary options associated with this promotion.

      • getAttribute

        @Nullable
Object getAttribute​(@NotNull
                    String attributeName)

      • detachChanges

        void detachChanges()
        Marks build as build with detached changes, i.e. changes of this build will be shown in the next build too.

      • resetAgentsCompatibilityCache

        void resetAgentsCompatibilityCache()
        Resets promotion compatibility cache for all agents and agent types

      • resetRequirementsCache

        void resetRequirementsCache()

      • resetAllCompatibilityCaches

        void resetAllCompatibilityCaches()

      • resetIncompatibleAgentTypesCache

        void resetIncompatibleAgentTypesCache​(@Nullable
                                      Predicate<CompatibilityResult> compatibilityPredicate)

      • getAgentTypeCompatibilityMap

        @NotNull
Map<SAgentType,​CompatibilityResult> getAgentTypeCompatibilityMap​(@NotNull
                                                                       Collection<SAgentType> available)
        Returns map of agent types to compatibility result. Note: can return empty map if the current build promotion is marked for deletion or its build configuration no longer exists.
        Parameters:
        available -
        Returns:

      • getCheckoutDirectory

        @Nullable
String getCheckoutDirectory()

      • getRealOrDummyBuild

        @NotNull
SBuild getRealOrDummyBuild()

      • addBuildProblem

        void addBuildProblem​(@NotNull
                     BuildProblemData buildProblem)
        Adds build problem, currently it actually causes build failure
        Since:
        7.1

      • getFailureReasons

        @NotNull
List<BuildProblemData> getFailureReasons()
        Returns non-muted build problems for this promotion Note that this mathod may cause DB call, if you only require the fact if there are any failure reasons use hasFailureReasons which is guaranteed fast
        Since:
        7.1

      • getBuildProblems

        @NotNull
List<BuildProblem> getBuildProblems()
        Returns all build problems for this promotion with extended information about muting. The problems are sorted in order of their appearance.
        Returns:
        see above
        Since:
        7.1

      • getUnsortedBuildProblems

        @NotNull
Collection<BuildProblem> getUnsortedBuildProblems()
        Same as getBuildProblems() but returns problems in any order and can work faster because of that.
        Returns:
        build problems in no particular order
        Since:
        2020.1

      • getBuildChainProblems

        @NotNull
List<BuildProblem> getBuildChainProblems​(boolean omitInduced)
        If omitInduced is false, simply traverses all of the dependencies of this promotion and returns collection of all build problems (including this promotion own problems). If omitInduced is true, returns only those build problems which caused failure of this build promotion (root causes). Returned list will not have build problems of snapshot dependency type (see ErrorData.isSnapshotDependencyError(String)) as such problems are induced and never represent the root cause.
        Parameters:
        omitInduced - see above
        Returns:
        list of own problems as well as problems from snapshot dependencies transitively
        Since:
        2017.2

      • hasBuildProblemsOfType

        boolean hasBuildProblemsOfType​(@NotNull
                               String type)
        Returns:
        true if there are build problems with specified type

      • hasFailureReasons

        boolean hasFailureReasons()

      • muteBuildProblems

        void muteBuildProblems​(boolean muteIfTrue,
                       @Nullable
                       SUser user,
                       @Nullable
                       String comment)
        Makes all existing build problems enabled or disabled
        Parameters:
        muteIfTrue - pass true to make build successful, false to make existing problems visible again
        Since:
        7.1

      • deleteBuildProblem

        void deleteBuildProblem​(@NotNull
                        String identity)
        Deletes build problem Deleting build problem may change build status to SUCCESS
        Parameters:
        identity - identiry of build problem to be removed
        Since:
        7.1

      • updateStateFromBuildData

        void updateStateFromBuildData​(@NotNull
                              AbstractBuildData runningBuildData)
        Quickly updates some information in build promotion from DB information. Doesn't store anything back to DB
        Parameters:
        runningBuildData -

      • updateSelfAndDependenciesFromDB

        void updateSelfAndDependenciesFromDB()
        Updates the build promotion and all its dependencies from the database

      • initBuildProblems

        void initBuildProblems()
        Init build problems from database

      • fillDetectedChanges

        void fillDetectedChanges​(@NotNull
                         List<ChangeDescriptor> accumulator,
                         @NotNull
                         SelectPrevBuildPolicy prevBuildPolicy,
                         @Nullable
                         Boolean includeDependencyChanges,
                         @NotNull
                         VcsModificationProcessor callback)
        Parameters:
        accumulator - collection to add changes to, according to 'prevBuildPolicy' and 'includeDependencyChanges' options. Changes included are guaranteed to be at or _more_ than defined by the cut-off point in 'callback'
        prevBuildPolicy -
        includeDependencyChanges -
        callback - allows to define changes iteration cut-off logic

      • getDetectedChanges

        @NotNull
List<ChangeDescriptor> getDetectedChanges​(@NotNull
                                          ChangesCalculationOptionsEx options)
        Returns changes according to the specified options
        Parameters:
        options - changes calculation options
        Returns:
        see above

      • fillDetectedChanges

        void fillDetectedChanges​(@NotNull
                         List<ChangeDescriptor> accumulator,
                         @NotNull
                         ChangesCalculationOptionsEx options)
        Computes changes according to the specified options and add them to the given accumulator
        Parameters:
        accumulator - accumulator for changes
        options - changes calculation options

      • getPersonalChanges

        @NotNull
List<ChangeDescriptor> getPersonalChanges​(@NotNull
                                          List<ChangeDescriptor> allChanges)
        Takes all changes and returns only those that belong to current owner of build promotion. Returns empty list of build promotion is not personal.
        Parameters:
        allChanges -
        Returns:

      • getOwnChanges

        @NotNull
List<SVcsModification> getOwnChanges​(@NotNull
                                     ChangesCalculationOptions options)
        Returns changes in this promotion computed according to specified options, doesn't include changes from dependencies.
        Parameters:
        options - changes calculation options
        Returns:
        see above

      • getDetectedChangesProviders

        @NotNull
List<BuildDetectedChangesProvider> getDetectedChangesProviders​(@NotNull
                                                               SelectPrevBuildPolicy prevBuildPolicy,
                                                               @Nullable
                                                               Boolean includeDependencyChanges)
        Parameters:
        prevBuildPolicy - previous build policy
        includeDependencyChanges - whether to include
        Returns:
        list of detected changes provides. Change provider returns changes associated with build promotion. With help of this method one can retrieve changes from some providers only.
        Since:
        7.1.1

      • getAllRevisionsMap

        @NotNull
Map<VcsRootInstance,​BuildRevisionEx> getAllRevisionsMap()
        Returns all vcs root revisions assciated with build, not only regular vcs roots attached to the build configurations.
        Returns:
        see above
        Since:
        8.0

      • getUpperLimitRevisions

        @NotNull
Map<VcsRootInstance,​BuildRevisionEx> getUpperLimitRevisions()
        Returns upper limit revisions which were available when checking for changes operation was performed. Upper limit revision is a revision returned by VcsRootInstance.getCurrentRevision() method at the moment when checking for changes was performed.
        Since:
        2023.11

      • getInternalBranchName

        @NotNull
String getInternalBranchName()
        Returns:
        internal branch name associated with build promotion. If build promotion belongs to default branch or is not branched, returns empty string.

      • getAutogeneratedBranchName

        @Nullable
String getAutogeneratedBranchName()
        Returns auto-generated branch name for the case if build promotion VCS roots differ from VCS roots in build configuration. The auto-generated name will have diff of changed settings.
        Returns:
        auto-generated name or null if settings do not differ

      • sameBranch

        boolean sameBranch​(@NotNull
                   BuildPromotionEx promotion)
        Parameters:
        promotion -
        Returns:
        true if this promotion is from the same branch as promotion specified in parameter.

      • resetChangesCache

        void resetChangesCache()
        Resets cache of changes in this promotion

      • getAuditLogActions

        @NotNull
List<AuditLogAction> getAuditLogActions​(@Nullable
                                        AuditLogFilter filter)
        Parameters:
        filter - if not null the filter is applied to the returned set of objects
        Returns:
        audit log actions associated with this promotion

      • getAuditLog

        @NotNull
AuditLog getAuditLog()
        Returns:
        audit log which can be used to log user actions for this build promotion

      • resetLogActionsCache

        void resetLogActionsCache()
        Reset cached audit log

      • resetTagsCache

        void resetTagsCache()
        Reset cached tags

      • getAgentCompatibility

        @NotNull
CompatibilityResult getAgentCompatibility​(@NotNull
                                          AgentDescription agentDescription)
        Parameters:
        agentDescription - agent or agent type
        Returns:
        compatibility of this build promotion with specified agent description (agent or agent type)

      • updateDependenciesCache

        void updateDependenciesCache​(@NotNull
                             Supplier<Map<Long,​Integer>> newDependenciesSupplier)
        Updates dependencies cache of the promotion and resets "dependent on me" cache of the supplied dependencies.

      • resetDependenciesHardRefs

        void resetDependenciesHardRefs()
        Each newly created build promotion keeps a reference to its direct dependencies (BuildPromotion instances). These references are kept to avoid removal of them by GC. Once these dependencies are persisted to DB, these hard refs are no longer required. At this point this method should be called to free some memory.

      • getSettingsDigest

        @NotNull
byte[] getSettingsDigest​(boolean compute)
        Returns digest of build promotion settings. If build promotion has build, then digest will be taken from the build artifacts. If there is no digest in artifacts, it will be computed by current settings if compute is set to true. Digest is always computed if build promotion does not have build associated. Returns empty array if digest cannot be computed or build does not have digest and compute is set to false
        Parameters:
        compute - if true and build promotion has build without digest, then digest will be calculated

      • hasComputedArtifactsState

        boolean hasComputedArtifactsState()

      • getArtifacts

        @NotNull
BuildArtifacts getArtifacts​(@NotNull
                            BuildArtifactsViewMode mode)
        Returns artifacts of this build promotion.
        Parameters:
        mode - artifacts view mode
        Returns:
        object describing artifacts of this build promotion.

      • artifactsChanged

        void artifactsChanged​(boolean scheduleUpdate)
        Should be called when artifacts are changed on disk.
        Parameters:
        scheduleUpdate - if true, a task should be scheduled to update artifacts state

      • hasUnpublishedPromotionPersistingEvent

        boolean hasUnpublishedPromotionPersistingEvent()
        Returns:
        true if "promotion persisted" event for this build promotion is not yet stored in DB

      • resetArtifactsState

        void resetArtifactsState​(boolean scheduleUpdate)
        Resets current artifacts state in the build promotion
        Parameters:
        scheduleUpdate - if true, a task should be scheduled to update artifacts state, otherwise state will be calculated when getArtifactStateInfo() is called

      • setQueuedAt

        void setQueuedAt​(Date queuedAt)

      • setRemoveFromQueueDate

        void setRemoveFromQueueDate​(@Nullable
                            Date removeFromQueueDate)

      • resetBuildLog

        void resetBuildLog()

      • buildFinished

        void buildFinished()
        Must be called when build history entry created for this promotion.

      • buildEvictedFromCache

        void buildEvictedFromCache()
        Called when finished build associated with this promotion is removed from the builds cache. In this case promotion can clear some of its internal objects and free some memory.

      • freezeSettings

        void freezeSettings()
             throws IOException
        Freeze buildType settings for this promotion. After call to this method a promotion will use frozen buildType settings instead of current ones.
        Throws:
        IOException - when freeze fails

      • freezeSettings

        void freezeSettings​(@NotNull
                    BuildTypeEx buildType,
                    @NotNull
                    String settingsOrigin)
             throws IOException
        Freeze buildType settings for this promotion using the given buildType. After call to this method a promotion will use frozen buildType settings instead of current ones.
        Parameters:
        buildType - buildType those settings to use
        settingsOrigin - origin of settings, predefined values: 'vcs' for settings from vcs, 'current' for current buildType settings
        Throws:
        IOException - when freeze fails

      • freezeSettings

        void freezeSettings​(@NotNull
                    BuildTypeSettingsEx settings,
                    @NotNull
                    String settingsOrigin)
             throws IOException
        Freeze settings for this promotion using the given buildSettings.
        Parameters:
        settings - the settings to store into the build promotion
        settingsOrigin - origin of settings, predefined values: 'vcs' for settings from vcs, 'current' for current buildType settings
        Throws:
        IOException - when freeze fails

      • freezeSettingsWithForcedPostprocessing

        void freezeSettingsWithForcedPostprocessing​(@NotNull
                                            BuildTypeSettingsEx settings,
                                            String origin)
                                     throws IOException
        Freeze settings for this promotion using the given buildSettings and mark that postprocessing is still required for this promotion.
        Parameters:
        settings - the settings to store into the build promotion
        origin - origin of settings, predefined values: 'vcs' for settings from vcs, 'current' for current buildType settings
        Throws:
        IOException - when freeze fails

      • freezeSettings

        void freezeSettings​(@NotNull
                    File settings,
                    @NotNull
                    String settingsOrigin)
             throws IOException
        Freeze settings for this promotion using the given settings file.
        Parameters:
        settings - the settings file to store into the build promotion
        settingsOrigin - origin of settings, predefined values: 'vcs' for settings from vcs, 'current' for current buildType settings
        Throws:
        IOException - when freeze fails

      • setFreezeSettings

        void setFreezeSettings​(@Nullable
                       Boolean freezeSettings)
        Indicates if we should freeze settings in build
        Parameters:
        freezeSettings - true means freeze settings if it is enabled for buildType, false means don't attempt to freeze settings even if they are enabled, null means use buildType's defaults (it is default value)

      • getFreezeSettings

        @Nullable
Boolean getFreezeSettings()
        Returns true if we should freeze settings if it is enabled in buildType, false if settings shouldn't be frozen, null - use buildType's defaults
        Returns:
        see above

      • getFrozenSettingsFile

        @NotNull
File getFrozenSettingsFile()
        Returns:
        path to file with frozen settings.

      • hasFrozenSettings

        boolean hasFrozenSettings()
        Returns:
        true if settings of this promotion were frozen.

      • hasFrozenSettingsFromVcs

        boolean hasFrozenSettingsFromVcs()
        Returns:
        true if this promotion has frozen settins from VCS

      • needToFreezeSettings

        boolean needToFreezeSettings()
        Returns:
        true if there was no attempt to freeze settings (successful or failed)
        Since:
        2021.1

      • scheduleCheckingForChangesIfNeeded

        boolean scheduleCheckingForChangesIfNeeded()
        Returns:
        true if checking for changes was scheduled and false if it was not, because build promotion has changes collected already

      • cancelCheckingForChanges

        void cancelCheckingForChanges()

      • getVcsRootEntries

        @NotNull
List<VcsRootInstanceEntry> getVcsRootEntries​(boolean includeSettingsRoot)
        Returns entries for VCS roots associated with this promotion. If promotion has an implicit settings root (not attached to buildType) and includeSettingsRoot is true, then an entry for this settings root is included in the result.
        Parameters:
        includeSettingsRoot - whether settings root should be included in result
        Returns:
        see above
        Since:
        9.1
        See Also:
        BuildTypeEx.getVcsRootInstanceEntries(boolean)

      • getRequirements

        @NotNull
List<Requirement> getRequirements()
        Returns requirements configured for this build promotion. If a requirement has a parameter reference in it's settings, this parameter reference will be resolved according to current promotion settings. Only enabled requirements are returned by this method.
        Returns:
        see above
        Since:
        2018.1

      • getRunnersRequirements

        @NotNull
List<Requirement> getRunnersRequirements​(@NotNull
                                         SBuildStepsCollection buildSteps)
        Returns requirements exposed by runners.
        Parameters:
        buildSteps -
        Returns:

      • getBuildFeaturesRequirements

        @NotNull
List<Requirement> getBuildFeaturesRequirements()
        Returns requirements coming by build features, resolved
        Returns:
        see above
        Since:
        2019.1

      • getBuildLog

        @NotNull
BuildLogEx getBuildLog()
        Specified by:
        getBuildLog in interface BuildPromotion
        Returns:
        Log for operations which could occur before build start, like changes collecting or logging detailed triggering information.

      • getBuildLogIfInitialized

        @Nullable
BuildLogEx getBuildLogIfInitialized()

      • createOrderedBuild

        @NotNull
OrderedBuild createOrderedBuild()
        Returns an OrderedBuild with all fields filled. The OrderedBuild contains a consistent snapshot of the promotion properties, ie. no one modified promotion during OrderedBuild creation.
        Returns:
        see above

      • hasLoadedTags

        boolean hasLoadedTags()
        Returns true if promotion loaded information about tags from db
        Returns:
        see above

      • isEquivalentTo

        @NotNull
EquivalenceCheckResult isEquivalentTo​(@NotNull
                                      BuildPromotion promoToCompare,
                                      @Nullable
                                      Boolean compareBranches)
        Parameters:
        promoToCompare - build promotion to compare with
        compareBranches - whether to compare branches strictly or not
        Returns:
        object with reason why builds are not equivalent
        Since:
        2019.1

      • setArtifactsDirectory

        void setArtifactsDirectory​(@NotNull
                           File artifactsDir)
        Sets new artifacts directory to this build promotion. This method also persists new artifacts directory in database, not additional call to persist() is required.
        Parameters:
        artifactsDir - new artifacts directory
        Since:
        10.0

      • isFinished

        boolean isFinished()
        Returns:
        true if build associated with this promotion is finished. Method is not optimized for performance, and can perform one SQL query to determine whether build is finished or not.
        Since:
        10.0

      • getProjectPathIds

        @NotNull
List<String> getProjectPathIds()
        Returns project path of a project where this build promotion belongs. Project path is fixed on the moment when some build is associated with this promotion. List contains internal ids of the projects. The first element in the list is root project id, while the last element contains id of the build promotion project.
        The list can be empty.
        Since:
        10.0

      • getOwnerNodeUrl

        @Nullable
String getOwnerNodeUrl()
        Returns url of the node which processes this build messages. Returns null if this build promotion is not assigned to any node. Returns MAIN_NODE_MARKER if build promotion was specifically assigned to main node.

      • getOwnerNode

        @Nullable
TeamCityNode getOwnerNode()
        Returns:
        TeamCityNode of build messages processor type if this promotion was assigned to such a node using setOwnerNodeUrl call; returns null in all other cases.

      • setOwnerNodeUrl

        void setOwnerNodeUrl​(@Nullable
                     String url)
        Sets url of the node which processes this build messages.
        Parameters:
        url -

      • getPreviousBuilds

        @NotNull
Stream<OrderedBuild> getPreviousBuilds​(@NotNull
                                       Filter<String> branchFilter)
        Returns stream of previous builds matched by specified branch filter and ordered by changes
        Parameters:
        branchFilter - filter of interest
        Returns:
        see above

      • containsChange

        boolean containsChange​(@NotNull
                       SVcsModification m)
        Returns true if promotion contains specified modification among its changes. Takes only own changes into account (does not use changes from dependencies).
        Parameters:
        m - modification of interest
        Returns:
        see above
        Since:
        10.0.3

      • allDependenciesFinished

        boolean allDependenciesFinished()
        Returns:
        true if all direct dependencies of this build promotion are finished

      • getDependentCompositePromotions

        @NotNull
List<BuildPromotionEx> getDependentCompositePromotions()
        Returns:
        list of all composite promotions depending on this build promotion either directly or transitively

      • getSettingsVcsRootInstance

        @Nullable
VcsRootInstance getSettingsVcsRootInstance()
        Returns:
        settings VCS root associated with this promotion
        Since:
        2019.1

      • decreaseExpirationCounter

        int decreaseExpirationCounter​(int decreaseAmount)

      • setExpirationCounter

        void setExpirationCounter​(int counter)

      • isAssociatedBuildFinished

        boolean isAssociatedBuildFinished()

      • associatedBuildFinished

        void associatedBuildFinished()

      • isForcedPostprocessingOfFrozenSettings

        boolean isForcedPostprocessingOfFrozenSettings()
        Returns:
        true if settings post processing is required even if settings are already marked as frozen

      • resetBuildSettings

        void resetBuildSettings()
        Resets cached build settings associated with promotion
        Since:
        2019.1

      • hasArtifactDependencyOn

        boolean hasArtifactDependencyOn​(@NotNull
                                BuildPromotion dependencyBuild)
        Checks if this promotion artifact-depends on the passed one. Especially useful for queued and running builds
        Since:
        2019.1

      • getBuildPromotionsWithArtifactDependenciesOnMe

        @NotNull
List<BuildPromotion> getBuildPromotionsWithArtifactDependenciesOnMe​(@NotNull
                                                                    List<BuildPromotion> buildPromotions)
        Checks artifact dependencies of the build promotions provided as an argument and returns those which have a direct artifact dependency (by build id) on this build promotion.
        Parameters:
        buildPromotions - build promotions to check
        Returns:
        the dependent build promotions
        Since:
        2024.07

      • isAgentLessBuild

        boolean isAgentLessBuild()
        Does it build cannot be executed on any usual agent but only by some external proccess.
        Specified by:
        isAgentLessBuild in interface BuildPromotionInfo
        Returns:
        true if the build cannot be executed on any usual agent; false - if the build can be executed on usual agent
        Since:
        2019.2

      • getPreviousOrderedBuild

        @Nullable
OrderedBuild getPreviousOrderedBuild​(@NotNull
                                     SelectPrevBuildPolicy policy)
        Returns previous OrderedBuild instance which corresponds to a build promotion which is created before this one and corresponding to the specified policy.
        Parameters:
        policy - policy
        Returns:
        see above

      • persistVcsRootEntries

        void persistVcsRootEntries()
        Persists information about VCS roots used by this build promotion to the database.

      • persistDependencies

        void persistDependencies()

      • getExecutionTimeoutMin

        int getExecutionTimeoutMin()
        Returns build execution timeout in minutes, 0 indicates that there is no limit

      • isDetachedFromAgent

        boolean isDetachedFromAgent()
        Returns:
        true if the corresponding build was detached from agent at some point and became agentless
        Since:
        2020.2

      • getDetachedFromAgentDate

        @Nullable
Date getDetachedFromAgentDate()
        Returns:
        date when this build was fully detched from agent or null
        Since:
        2020.2

      • getPromotionCustomization

        @NotNull
PromotionCustomizationInfo getPromotionCustomization()
        Returns promotion customization details, if any Build promotion can be customized by pressing ... near "Run" button in the configuration. The customization may include revisions, dependencies, custom parameters. Personal builds are marked as customized only if other some build parameters differ from typical one.
        Returns:
        see above
        Since:
        2020.2

      • getCommitters

        @NotNull
Set<SUser> getCommitters​(@NotNull
                         SelectPrevBuildPolicy selectPrevBuildPolicy,
                         int maxChangesToProcess)
        Same as BuildPromotion.getCommitters(SelectPrevBuildPolicy) but allows to control number of changes which should be looked up when committers are computed.
        Parameters:
        selectPrevBuildPolicy - policy for selecting a previous build
        maxChangesToProcess - max number of changes in build to look up, -1 indicates no limit
        Returns:
        committers from builds changes
        Since:
        2020.2.3

      • getDependenciesSupplier

        @NotNull
DependenciesSupplier getDependenciesSupplier()
        Creates a dependencies supplier from the snapshot dependencies of this build promotion.
        Returns:
        see above
        Since:
        2022.04

      • resetDirectDependenciesCache

        void resetDirectDependenciesCache()
        reset only direct dependencies cache of the promotion.
        Since:
        2022.10

      • resetDependentOnMeCache

        void resetDependentOnMeCache()
        reset only dependent on this cache of the promotion.
        Since:
        2022.10

      • ensureBuildLogFlushed

        void ensureBuildLogFlushed()
        Makes sure that messages in the build log buffer are flushed on disk.

      • generateAgentAccessCode

        String generateAgentAccessCode()
        Generates agent access code for communication with TeamCity during build

      • setProvidedUpperLimitRevisions

        void setProvidedUpperLimitRevisions​(@NotNull
                                    Map<Long,​RepositoryVersion> upperLimitRevisions)
                             throws IllegalArgumentException
        Sets custom/provided upper limit revisions which will be used during the checking for changes process instead of the current repository version.
        Parameters:
        upperLimitRevisions - map of VCS root instance id to revision object, vcs root instance can belong to the current build or its dependencies
        Throws:
        IllegalArgumentException - if provided VCS branch name or revision is too long (longer than 1000 characters)
        Since:
        2024.07

      • getProvidedUpperLimitRevisions

        @NotNull
Map<Long,​RepositoryVersion> getProvidedUpperLimitRevisions()
        Returns:
        map of provided upper limit revisions for the checking for changes process
        Since:
        2024.07

      • getVersionedSettingsRevision

        @Nullable
String getVersionedSettingsRevision​(@NotNull
                                    VcsRootInstance vcsRoot)
        Returns a revision of versioned settings for the given VCS root instance or null if such a revision does not exist.
        Parameters:
        vcsRoot -
        Returns:
        see above
        Since:
        2024.07

      • setVersionedSettingsRevision

        void setVersionedSettingsRevision​(@NotNull
                                  VcsRootInstance vcsRoot,
                                  @NotNull
                                  String revision)
        Remmebers versioned settings revision for the specified VCS root. Note: persist must be called explicitly for the information to be saved into the database. See also getVersionedSettingsRevision(VcsRootInstance).
        Parameters:
        vcsRoot -
        revision -
        Since:
        2024.07

      • getAnchorBuildPromotion

        @Nullable
BuildPromotionEx getAnchorBuildPromotion()
        For the build promotion which runs in a virtual build configuration returns a build promotion which created it. The anchor build promotion is visible to the user and collects all the results of the virtual build promotions.
        Returns:
        see above
        Since:
        2024.07

      • isVirtual

        boolean isVirtual()
        Returns:
        true if the build promotion is running in a virtual build configuration
        Since:
        2024.07

      • occupiesLicenseSlot

        boolean occupiesLicenseSlot()
        Returns true when this build promotion should occupy one of license slots, false otherwise. Currently, the number of license slots is equal to the max number of authorized agents.
        Returns:
        see above
        Since:
        2024.12
        See Also:
        LicensingPolicy.getMaxNumberOfAuthorizedAgents()