Interface BuildTypeSettings

    • Method Detail

      • getProject

        @NotNull
        SProject getProject()
        Returns the project this build type entity belongs to.
        Returns:
        the project this build type entity belongs to.
      • getRunnerTypes

        @NotNull
        Collection<String> getRunnerTypes()
        Returns types of the runners attached to these settings
        Returns:
        see above
        Since:
        6.0
      • getRunTypeRequirements

        @NotNull
        List<Requirement> getRunTypeRequirements()
        Returns list of additional agent requirements imposed by configured runners.
        Returns:
        see above
      • getBuildFeatureRequirements

        @NotNull
        List<Requirement> getBuildFeatureRequirements()
        Returns list of additional agent requirements imposed by configured enabled build features.
        Returns:
        see above
        Since:
        2019.1
      • addBuildRunner

        @NotNull
        SBuildRunnerDescriptor addBuildRunner​(@NotNull
                                              String id,
                                              @NotNull
                                              String name,
                                              @NotNull
                                              String runnerType,
                                              @NotNull
                                              Map<String,​String> parameters)
                                       throws DuplicateIdException,
                                              InvalidIdentifierException,
                                              ReadOnlyEntityException
        Creates a new build runner with the specified id, name, runner type, and parameters, and adds it to the current build settings.
        Parameters:
        id - the unique id of the build runner (should be unique within all runners of this configuration)
        name - the name of the build runner
        runnerType - the type of the build runner
        parameters - the parameters for the build runner
        Returns:
        the newly created build runner descriptor
        Throws:
        DuplicateIdException - if the id is already in use by another build runner, runners inherited from templates are not considered
        InvalidIdentifierException - if the id is invalid or empty
        ReadOnlyEntityException - if the settings are read-only and cannot be modified
        Since:
        2023.09
      • updateBuildRunner

        boolean updateBuildRunner​(@NotNull
                                  String runnerId,
                                  @NotNull
                                  String newName,
                                  @NotNull
                                  String newType,
                                  @NotNull
                                  Map<String,​String> newParams)
                           throws ReadOnlyEntityException
        Updates parameters in the existing build runner descriptor. Does nothing if there runner with specified id was not found.
        Parameters:
        runnerId - id of runner descriptor
        newName - new runner name
        newType - new type of the runner
        newParams - new runner parameters
        Returns:
        true if parameters updated and false otherwise
        Throws:
        ReadOnlyEntityException
        Since:
        6.5
      • getBuildRunners

        @NotNull
        List<SBuildRunnerDescriptor> getBuildRunners()
        Returns collection of build runners attached to these settings
        Returns:
        see above
        Since:
        6.0
      • getRunnersOrder

        @Nullable
        String[] getRunnersOrder()
        Returns:
        runner ids in their custom order (if such order is set), null otherwise
      • applyRunnersOrder

        void applyRunnersOrder​(@NotNull
                               String[] ids)
                        throws ReadOnlyEntityException
        Accepts array of runner identifiers and reorders them according to this array.
        Parameters:
        ids - runner identifiers
        Throws:
        ReadOnlyEntityException
        Since:
        6.0
      • findBuildRunnerByType

        @Nullable
        SBuildRunnerDescriptor findBuildRunnerByType​(@NotNull
                                                     String runnerType)
        Finds build runner by its' type. If there is more than one build runner, returns the first one.
        Parameters:
        runnerType - type of the runner
        Returns:
        build runner or null if runner was not found
        Since:
        6.0
      • findBuildRunnerById

        @Nullable
        SBuildRunnerDescriptor findBuildRunnerById​(@NotNull
                                                   String runnerId)
        Finds build runner by its' id
        Parameters:
        runnerId - id of the runner
        Returns:
        build runner or null if runner with such id not found
        Since:
        6.0
      • findRunnerParameter

        @Nullable
        String findRunnerParameter​(@NotNull
                                   String paramName)
        Searches runner parameter in all build runners and returns value of the first found parameter with given name.
        Parameters:
        paramName - name of the parameter
        Returns:
        the first found parameter value or null
        Since:
        6.0
      • getBuildParameters

        @NotNull
        Map<String,​String> getBuildParameters()
        Return map of build parameters specified by user. Each build parameter has name and value. Name of each parameter starts from a prefix: env. or system. Value may by either simple string, or may contain references to other parameters in form %env.HOME% or %system.os.name% or %system.agent.name%
        Returns:
        see above
      • getBuildParametersCollection

        @NotNull
        Collection<Parameter> getBuildParametersCollection()
        Returns build parameters collection.
        Returns:
        see above
      • getBuildParameter

        String getBuildParameter​(String key)
        Returns build parameter by parameter key
        Parameters:
        key - parameter key
        Returns:
        build parameter by parameter key
      • getVcsRoots

        @NotNull
        List<SVcsRoot> getVcsRoots()
        Returns all roots currently attached to this configuration
        Returns:
        collection of all attached vcs roots.
      • removeBuildTrigger

        boolean removeBuildTrigger​(@NotNull
                                   BuildTriggerDescriptor triggerDescriptor)
                            throws ReadOnlyEntityException
        Removes specified build trigger from the settings
        Parameters:
        triggerDescriptor - trigger descriptor
        Returns:
        true if trigger was actually removed and false otherwise
        Throws:
        ReadOnlyEntityException
        Since:
        5.1
      • updateBuildTrigger

        boolean updateBuildTrigger​(@NotNull
                                   String triggerId,
                                   @NotNull
                                   String newType,
                                   @NotNull
                                   Map<String,​String> newParams)
                            throws ReadOnlyEntityException
        Updates build trigger descriptor with specified id, changes type and parameters.
        Parameters:
        triggerId - id of build trigger descriptor
        newType - type of build trigger descriptor
        newParams - parameters map
        Returns:
        true if parameters of build trigger descriptor were changed (descriptor with such id exists) and false otherwise
        Throws:
        ReadOnlyEntityException
        Since:
        7.0
      • updateBuildTrigger

        boolean updateBuildTrigger​(@NotNull
                                   BuildTriggerDescriptor newDescriptor)
        Updates build trigger descriptor with id equal to newDescriptor id.
        Parameters:
        newDescriptor - new settings of the trigger
        Returns:
        true if parameters of build trigger descriptor were changed (descriptor with such id exists) and false otherwise
      • getBuildTriggersCollection

        @NotNull
        Collection<BuildTriggerDescriptor> getBuildTriggersCollection()
        Returns collection of build trigger settings
        Returns:
        see above
        Since:
        5.1
      • findTriggerById

        @Nullable
        BuildTriggerDescriptor findTriggerById​(@NotNull
                                               String triggerId)
        Finds build trigger descriptor by its' id
        Parameters:
        triggerId - id of the trigger
        Returns:
        build trigger descriptor or null if trigger with such id not found
        Since:
        6.0
      • getCheckoutDirectory

        @Nullable
        String getCheckoutDirectory()

        Returns build checkout directory - if specified explicitly using setCheckoutDirectory(String). Returns null if default checkout directory, generated by TeamCity should be used.

        Returns:
        build checkout directory.
        See Also:
        setCheckoutDirectory(String)
      • setArtifactPaths

        void setArtifactPaths​(@Nullable
                              String artifactPaths)
                       throws ReadOnlyEntityException
        Sets build artifact paths. Artifact paths are comma separated paths to build artifacts. Support ant-style wildcards and target directories like *.zip => winFiles,unix/dist.tgz => linuxFiles, where winFiles and linuxFiles are target directories. Set to null or empty string to disable artifacts processing.
        Parameters:
        artifactPaths - paths to build artifacts
        Throws:
        ReadOnlyEntityException
        Since:
        8.1 same as #setOption(BuildTypeOptions#BT_ARTIFACT_RULES, rules)}
      • getArtifactPaths

        @Nullable
        String getArtifactPaths()
        Returns build artifact paths.
        Returns:
        build artifact paths
        Since:
        8.1 same as #getOption(BuildTypeOptions#BT_ARTIFACT_RULES)}
      • getArtifactDependencies

        @NotNull
        List<SArtifactDependency> getArtifactDependencies()
        Returns artifacts this build configuration depending on.
        Returns:
        list of artifacts this build configuration depending on
      • containsVcsRoot

        boolean containsVcsRoot​(long vcsRootId)
        Returns true if VCS root with specified id is attached directly or is inherited via a template
        Parameters:
        vcsRootId - id of VCS root
        Returns:
        see above
      • containsOwnVcsRoot

        boolean containsOwnVcsRoot​(long vcsRootId)
        Returns true if VCS root with specified id is attached directly and is not inherited via a template
        Parameters:
        vcsRootId - id of VCS root
        Returns:
        see above
        Since:
        2019.2
      • getVcsRootEntries

        @NotNull
        List<VcsRootEntry> getVcsRootEntries()
        Returns all entries of vcs roots. Each entry contains reference to root and its checkout rules.
        Returns:
        all entries of vcs roots for this configuration
      • removeVcsRoot

        boolean removeVcsRoot​(@NotNull
                              SVcsRoot root)
                       throws ReadOnlyEntityException
        Removes existing VCS root from the build configuration. If there were checkout rules attached to this VCS root they will be removed too.
        Parameters:
        root - VCS root to remove
        Returns:
        true if VCS root was actually removed from the build configuration and false if build configuration did not have this vcs root attached
        Throws:
        ReadOnlyEntityException
      • setCheckoutRules

        boolean setCheckoutRules​(@NotNull
                                 VcsRoot root,
                                 @NotNull
                                 CheckoutRules checkoutRules)
                          throws ReadOnlyEntityException
        Sets checkout rules for specified VCS root. VCS root must be attached to this build configuration.
        Parameters:
        root - root to set rules for
        checkoutRules - checkout rules for the VCS root
        Returns:
        true if checkout rules were set for the VCS root (if VCS root is attached) and false otherwise
        Throws:
        ReadOnlyEntityException
      • getCheckoutRules

        @Nullable
        CheckoutRules getCheckoutRules​(@NotNull
                                       VcsRoot root)
        Returns checkout rules configured for the specified VCS root. If specified VCS root is not attached to this build configuration, then null is returned.
        Parameters:
        root - VCS root
        Returns:
        checkout rules or null if specified VCS root is not attached to the build configuration
      • addConfigParameter

        void addConfigParameter​(@NotNull
                                Parameter param)
                         throws ReadOnlyEntityException
        Adds configuration parameter. There are three different types of parameters which can be added to build configuration settings:
        • build parameters - these are parameters passed to agent and then to a build (see addBuildParameter(Parameter)), these parameters must have prefix system. or env.
        • runner parameters - these are parameters of a runner, they are transferred to agent and passed to corresponding build runner plugin
        • configuration parameters - these parameters are not transferred to agent or build, but can be referenced in various places (including build & runner parameters and thus can effectively pass to a build)
        Parameters:
        param - configuration parameter
        Throws:
        ReadOnlyEntityException
      • getConfigParametersCollection

        @NotNull
        Collection<Parameter> getConfigParametersCollection()
        Returns collection of configuration parameters.
        Returns:
        see above
      • getConfigParameters

        @NotNull
        Map<String,​String> getConfigParameters()
        Returns map of configuration parameters
        Returns:
        see above
      • getUndefinedParameters

        @NotNull
        List<String> getUndefinedParameters()
        Returns collection of parameter names (config and build params) referenced in the build configuration settings but without values provided. I.e. there is a reference to a parameter but such parameter is not defined anywhere.
        Parameter value can come from different sources:
        • build configuration or template settings
        • agents
        • various extensions
        Returns:
        see above
        Since:
        6.0
      • isTemplateBased

        boolean isTemplateBased()
        Returns true if these settings are directly based on a template. It does not take into account a default template.
        Returns:
        see above
      • getTemplates

        @NotNull
        List<? extends BuildTypeTemplate> getTemplates()
        Returns templates these settings are based on, including the default template.
        Returns:
        see above
        Since:
        2017.2
      • isTemplateAccessible

        boolean isTemplateAccessible()
        Checks accessibility of all attached templates, excluding the default template (if present)
        Returns:
        true if there are such templates and all of them are accessible to currently logged in user, false otherwise
        Since:
        8.1.3
      • getTemplateIds

        @NotNull
        List<String> getTemplateIds()
        Returns internal ids of the templates this settings are based on, including one of the default template
        Returns:
        see above
        Since:
        2017.2
      • getTemplateId

        @Nullable
        @Deprecated
        String getTemplateId()
        Deprecated.
        since 2017.2, use getTemplateIds() instead
        Returns internal id of the first template this setting is based on
        Returns:
        see above
      • getRequirements

        @NotNull
        List<Requirement> getRequirements()
        Get list of explicit requirements for build agents which can run this build configuration. Explicit requirements are specified by user in Web UI explicitly.
        Returns:
        see above
      • getImplicitRequirements

        @NotNull
        List<Requirement> getImplicitRequirements()
        Get list of non-satisfied implicit requirements for build agents. Implicit requirements appear when some build configuration property, or run parameter contains a reference to another parameter in form %<param name>%.
        Returns:
        see above
      • addRequirement

        void addRequirement​(@NotNull
                            Requirement requirement)
                     throws ReadOnlyEntityException
        Adds new build requirement to the configuration. If the requirement has no id, then a copy of it with new id is generated and added to the settings.
        Parameters:
        requirement - new requirement.
        Throws:
        ReadOnlyEntityException
      • removeRequirement

        void removeRequirement​(String parameterName)
                        throws ReadOnlyEntityException
        Removes first requirement with the specified property name from the configuration.
        Parameters:
        parameterName - name of the requirement parameter.
        Throws:
        ReadOnlyEntityException
      • getBuildNumberPattern

        @NotNull
        String getBuildNumberPattern()
        Returns current build number pattern
        Returns:
        see above
        Since:
        5.0
      • setBuildNumberPattern

        void setBuildNumberPattern​(@NotNull
                                   String pattern)
                            throws ReadOnlyEntityException
        Sets build number pattern. %build.counter% in the pattern will be replaced with current build number value when build starts
        Parameters:
        pattern - pattern to set
        Throws:
        ReadOnlyEntityException
        Since:
        5.0
      • replaceInValues

        boolean replaceInValues​(@NotNull
                                Pattern regexpPattern,
                                @NotNull
                                String replacement)
                         throws ReadOnlyEntityException
        Replaces values according to specified pattern and replacement string in all text parameters of the build configuration
        Parameters:
        regexpPattern - regexp pattern
        replacement - replacement
        Returns:
        true if at least one text value was affected and false otherwise
        Throws:
        ReadOnlyEntityException
        Since:
        8.0.7
      • textValueMatches

        boolean textValueMatches​(@NotNull
                                 Pattern regexpPattern)
        Returns true if configuration has value in text parameters which matches specified pattern. Only own parameters are checked - without inherited
        Parameters:
        regexpPattern - regexp pattern
        Returns:
        true if such value exists and false otherwise
        Since:
        8.0.7
      • getBuildFeatures

        @NotNull
        Collection<SBuildFeatureDescriptor> getBuildFeatures()
        Returns build features added to this settings object.
        Returns:
        collection of configured build features
        Since:
        6.0
      • getBuildFeaturesOfType

        @NotNull
        Collection<SBuildFeatureDescriptor> getBuildFeaturesOfType​(@NotNull
                                                                   String type)
        Returns all build features of specified type.
        Returns:
        see above
        Since:
        8.1
      • removeBuildFeature

        @Nullable
        SBuildFeatureDescriptor removeBuildFeature​(@NotNull
                                                   String featureId)
                                            throws ReadOnlyEntityException
        Removes build feature with specified id from this settings object.
        Parameters:
        featureId - id of the feature
        Returns:
        removed build feature descriptor or null if there were no feature descriptor with such id
        Throws:
        ReadOnlyEntityException
        Since:
        6.0
      • updateBuildFeature

        boolean updateBuildFeature​(@NotNull
                                   String featureId,
                                   @NotNull
                                   String newType,
                                   @NotNull
                                   Map<String,​String> newParams)
                            throws ReadOnlyEntityException
        Updates build feature descriptor with specified id, changes type and parameters.
        Parameters:
        featureId - id of build feature descriptor
        newType - type of build feature descriptor
        newParams - parameters map
        Returns:
        true if parameters of build feature descriptor were changed (descriptor with such id exists) and false otherwise
        Throws:
        ReadOnlyEntityException
        Since:
        6.0
      • findBuildFeatureById

        @Nullable
        SBuildFeatureDescriptor findBuildFeatureById​(@NotNull
                                                     String featureId)
        Returns build feature with specified id
        Parameters:
        featureId - id of the feature
        Returns:
        see above
        Since:
        8.1
      • setEnabled

        void setEnabled​(@NotNull
                        String parametersDescriptorId,
                        boolean enabled)
                 throws ReadOnlyEntityException
        Enables or disables descriptor with specified id in build configuration settings. This method can be used to enable or disable build runners, triggers and build features.
        Parameters:
        parametersDescriptorId - id of build runner, trigger or build feature
        enabled - true to enable, false to disable
        Throws:
        ReadOnlyEntityException
        Since:
        7.0
      • isEnabled

        boolean isEnabled​(@NotNull
                          String parametersDescriptorId)
        Returns true if descriptor with specified id (runner, trigger or build feature) is enabled and false otherwise.
        Parameters:
        parametersDescriptorId - id of build runner, trigger or build feature
        Since:
        7.0
      • getTypedOption

        @NotNull
        <T> TypedValue<T> getTypedOption​(@NotNull
                                         Option<T> option)

        Get option extended value. See TypedValue. When the option is not defined in this Settings TypedValue will contain null in getValue()

        Since:
        10.0
      • isDeployment

        boolean isDeployment()
        Returns:
        true if this build configuration is doing deployment
        Since:
        2020.1
      • isCompositeBuildType

        boolean isCompositeBuildType()
        Returns:
        true if this build type is composite
        Since:
        2017.2
      • isReadOnly

        boolean isReadOnly()
        Returns:
        true if these settings are in read only mode
        Since:
        2021.1
      • getReadOnlyReason

        @Nullable
        ReadOnlyReason getReadOnlyReason()
        Returns:
        reason why these settings are in read only state or null if they are not read only
        Since:
        2021.1