Package com.atlassian.bamboo.deployments.versions.service

Interface DeploymentVersionService

    • Method Detail

      • validateCreateDeploymentVersion

        @NotNull
@NotNull ErrorCollection validateCreateDeploymentVersion​(long deploymentProjectId,
                                                         @NotNull
                                                         @NotNull PlanResultKey planResultKey,
                                                         @Nullable
                                                         @Nullable String name,
                                                         @Nullable
                                                         @Nullable String nextVersionName)
        Validates values to be used for creating a new version.
        Parameters:
        deploymentProjectId - id of the deployment project
        planResultKey - key of the build result on which this version is created
        name - version name
        nextVersionName - name of the next version
        Returns:
        errorCollection containing any errors found. If no errors, an empty errorCollection will be returned.

      • isVersionNameConflicting

        boolean isVersionNameConflicting​(long deploymentProjectId,
                                 @NotNull
                                 @NotNull String name)
        Check whether the version name is already being used by another version within this project
        Parameters:
        deploymentProjectId - project to filter by
        name - to check
        Returns:
        true if name is already being used.

      • validateDeploymentVersionRename

        @NotNull
@NotNull ErrorCollection validateDeploymentVersionRename​(long deploymentProjectId,
                                                         @NotNull
                                                         @NotNull DeploymentVersion deploymentVersion,
                                                         @Nullable
                                                         @Nullable String name)
        Validates values to be used for renaming version.
        Parameters:
        deploymentProjectId -
        deploymentVersion -
        name -
        Returns:
        errorCollection containing any errors found. If no errors, an empty errorCollection will be returned.

      • getOrCreateDeploymentVersion

        @NotNull
@NotNull DeploymentVersion getOrCreateDeploymentVersion​(long deploymentProjectId,
                                                        @NotNull
                                                        @NotNull PlanResultKey planResultKey)
                                                 throws WebValidationException
        Given a build result, find a deployment version that matches it, or create it if it doesn't exist. Uses automatic naming.
        Parameters:
        deploymentProjectId - of project to create version for
        planResultKey - of the result to pull artifacts from
        Returns:
        deployment version
        Throws:
        WebValidationException
        Since:
        5.6

      • createDeploymentVersion

        @NotNull
@NotNull DeploymentVersion createDeploymentVersion​(long deploymentProjectId,
                                                   @NotNull
                                                   @NotNull PlanResultKey planResultKey,
                                                   @Nullable
                                                   @Nullable com.atlassian.user.User user,
                                                   @Nullable
                                                   @Nullable String versionName,
                                                   @Nullable
                                                   @Nullable String nextVersionName)
                                            throws WebValidationException
        Create a deployment version with a specific name. From deployment project and plan result. Assumes validation of name has been done.
        Parameters:
        deploymentProjectId - project the version is getting created for
        planResultKey - of the result to pull artifacts from
        versionName - name for the version to create
        nextVersionName - the name for the next version (to be updated in version naming scheme)
        user - the person who is creating this version
        Returns:
        created Deployment Version.
        Throws:
        WebValidationException

      • getDeploymentVersion

        @Nullable
@Nullable DeploymentVersion getDeploymentVersion​(long deploymentVersionId)
        Get DeploymentVersion by id

      • getResultPlanKeysHavingDeploymentProjectVersions

        @NotNull
@NotNull Set<String> getResultPlanKeysHavingDeploymentProjectVersions​(long deploymentProjectId)
        Returns keys of result plans (branch) that have at least one deployment project version (release)
        Parameters:
        deploymentProjectId - id of the deployment project
        Returns:

      • getDeploymentProjectVersions

        @NotNull
@Deprecated
@NotNull List<DeploymentVersion> getDeploymentProjectVersions​(long deploymentProjectId)
        Deprecated.
        since 6.7 for performance reasons use getDeploymentProjectVersionsNoVariables(DeploymentProject)
        Retrieves the list of all the version for the deployment project, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)

        This method fetches complete version data, getDeploymentProjectVersionsNoVariables(DeploymentProject) should be preferred when variable data is not required, e.g. for displaying list of version in the UI.

        Parameters:
        deploymentProjectId - id of the deployment project
        Returns:
        all the versions for the specified deployment project. Empty list if deployment project not found or if there is no versions for it.

      • searchVersionsByName

        @NotNull
@Deprecated
@NotNull List<DeploymentVersion> searchVersionsByName​(long deploymentProjectId,
                                                      @NotNull
                                                      @NotNull String searchTerm)
        Deprecated.
        since 6.7 for performance reasons use searchVersionsByNameNoVariables(DeploymentProject, String)
        Search for deployment versions in a project whose name contains the searchTerm, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)

        This method fetches complete version data, searchVersionsByNameNoVariables(DeploymentProject, String) should be preferred when variable data is not required, e.g. for displaying list of version in the UI.

        Parameters:
        deploymentProjectId - deployment project to search within
        searchTerm - term to look for.
        Returns:
        list of Deployment Versions matching the search criteria

      • searchVersionsByBranch

        @NotNull
@Deprecated
@NotNull List<DeploymentVersion> searchVersionsByBranch​(long deploymentProjectId,
                                                        @NotNull
                                                        @NotNull PlanKey branchKey)
        Deprecated.
        since 6.7 for performance reasons use searchVersionsByBranchNoVariables(DeploymentProject, PlanKey)
        Search for deployment versions in a project associated with a specific branch, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)

        This method fetches complete version data, searchVersionsByBranchNoVariables(DeploymentProject, PlanKey) should be preferred when variable data is not required, e.g. for displaying list of version in the UI.

        Parameters:
        deploymentProjectId - deployment project to search within
        branchKey - plan branch to narrow search result
        Returns:
        list of Deployment Versions matching the search criteria

      • searchVersionsByBranchAndName

        @NotNull
@Deprecated
@NotNull List<DeploymentVersion> searchVersionsByBranchAndName​(long deploymentProjectId,
                                                               @NotNull
                                                               @NotNull PlanKey branchKey,
                                                               @NotNull
                                                               @NotNull String searchTerm)
        Deprecated.
        since 6.7 for performance reasons use searchVersionsByNameNoVariables(DeploymentProject, String)
        Search for deployment versions in a project whose name contains the searchTerm, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)

        This method fetches complete version data, searchVersionsByBranchAndNameNoVariables(DeploymentProject, PlanKey, String) should be preferred when variable data is not required, e.g. for displaying list of version in the UI.

        Parameters:
        deploymentProjectId - deployment project to search within
        branchKey - plan branch to narrow search result
        searchTerm - term to look for.
        Returns:
        list of Deployment Versions matching the search criteria

      • searchVersionsByNameNoVariables

        @NotNull
@NotNull List<DeploymentVersion> searchVersionsByNameNoVariables​(@NotNull
                                                                 @NotNull DeploymentProject deploymentProject,
                                                                 @NotNull
                                                                 @NotNull String searchTerm)
        Search for deployment versions in a project whose name contains the searchTerm, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)
        Parameters:
        deploymentProject - deployment project to search within
        searchTerm - term to look for.
        Returns:
        list of Deployment Versions matching the search criteria
        Since:
        6.6

      • searchVersionsByBranchNoVariables

        @NotNull
@NotNull List<DeploymentVersion> searchVersionsByBranchNoVariables​(@NotNull
                                                                   @NotNull DeploymentProject deploymentProject,
                                                                   @NotNull
                                                                   @NotNull PlanKey branchKey)
        Search for deployment versions in a project associated with a specific branch, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)
        Parameters:
        deploymentProject - deployment project to search within
        branchKey - plan branch to narrow search result
        Returns:
        list of Deployment Versions matching the search criteria
        Since:
        6.6

      • searchVersionsByBranchNoVariables

        @NotNull
@NotNull List<DeploymentVersion> searchVersionsByBranchNoVariables​(@NotNull
                                                                   @NotNull DeploymentProject deploymentProject,
                                                                   @NotNull
                                                                   @NotNull PlanKey branchKey,
                                                                   int startIndex,
                                                                   int maxResults)
        Search for deployment versions in a project associated with a specific branch, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)
        Parameters:
        deploymentProject - deployment project to search within
        branchKey - plan branch to narrow search result
        Returns:
        list of Deployment Versions matching the search criteria
        Since:
        7.0

      • searchVersionsByBranchAndNameNoVariables

        @NotNull
@NotNull List<DeploymentVersion> searchVersionsByBranchAndNameNoVariables​(@NotNull
                                                                          @NotNull DeploymentProject deploymentProject,
                                                                          @NotNull
                                                                          @NotNull PlanKey branchKey,
                                                                          @NotNull
                                                                          @NotNull String searchTerm)
        Search for deployment versions in a project whose name contains the searchTerm and associated with a specific branch, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)
        Parameters:
        deploymentProject - deployment project to search within
        branchKey - plan branch to narrow search result
        searchTerm - term to look for.
        Returns:
        list of Deployment Versions matching the search criteria
        Since:
        6.6

      • getDeploymentVersionByName

        @Nullable
@Nullable DeploymentVersion getDeploymentVersionByName​(@NotNull
                                                       @NotNull String existingVersion,
                                                       long deploymentProjectId)
        Get a specific version by name
        Parameters:
        existingVersion - name of the version
        Returns:
        the Deployment version with given name if found, otherwise null.

      • getRelatedPlanResultKeys

        Set<PlanResultKey> getRelatedPlanResultKeys​(long deploymentVersionId)
        Retrieve the PlanResultKeys of ResultSummaries related to a particular DeploymentVersion

      • getRelatedPlanResultKeys

        @NotNull
@NotNull Map<Long,​PlanResultKey> getRelatedPlanResultKeys​(@NotNull
                                                                @NotNull Set<Long> deploymentVersionIds)
        Retrieve the PlanResultKeys of ResultSummaries related to a particular DeploymentVersions
        Since:
        9.3

      • isFromTheSameBranch

        boolean isFromTheSameBranch​(long firstVersionId,
                            long secondVersionId)
        Checks if both deployment versions come from the same branch
        Parameters:
        firstVersionId - first deployment version
        secondVersionId - second deployment version
        Returns:

      • isFromTheSameBranch

        boolean isFromTheSameBranch​(String planKey,
                            long versionId)
        Checks if the specified build result is on the same branch as the specified version ID
        Parameters:
        planKey - the planKey of the build result you want to compare
        versionId - the version ID of the version you want to compare
        Returns:

      • updateVersionStatus

        @NotNull
@NotNull DeploymentVersionStatus updateVersionStatus​(long deploymentVersionId,
                                                     @NotNull
                                                     @NotNull DeploymentVersionState status,
                                                     @NotNull
                                                     @NotNull String userName)
        Updates the version status for given deployment version.

      • getAllUsersLatestVersionStatusDtosOrderedByCreationDate

        @NotNull
@NotNull List<DeploymentVersionStatus> getAllUsersLatestVersionStatusDtosOrderedByCreationDate​(long deploymentVersionId)
        Returns:
        all users' version statuses for the requested deploymentVersionId.
        Since:
        9.4

      • findVersionsBetweenNoVariables

        @NotNull
@NotNull List<DeploymentVersion> findVersionsBetweenNoVariables​(@NotNull
                                                                @org.jetbrains.annotations.NotNull long deploymentProjectId,
                                                                @NotNull
                                                                @NotNull DeploymentVersion version1,
                                                                @NotNull
                                                                @NotNull DeploymentVersion version2)
        Find versions created between version1 and version2. The versions must be different but belong to the same DeploymentProject The order of the argument is irrelevant: the method will determine which of the versions is the lower bound. Lower bound is not included in result but upper bound is. The result is sorted by creation date (newest first)
        Throws:
        IllegalArgumentException - if any of the version doesn't exist

      • findPreviousVersion

        @Nullable
@Nullable DeploymentVersion findPreviousVersion​(long deploymentProjectId,
                                                long versionId)

      • getVersionsCount

        int getVersionsCount()
        Count all versions
        Returns:
        number of versions created in all deployment projects

      • getVersionsCountForProject

        int getVersionsCountForProject​(long deploymentProjectId)
        Count versions related to deployment project
        Parameters:
        deploymentProjectId - id of deployment project
        Returns:
        number of versions created in deployment project

      • getVersionsCountForProjectAndBranch

        int getVersionsCountForProjectAndBranch​(@NotNull
                                        @org.jetbrains.annotations.NotNull long deploymentProjectId,
                                        @NotNull
                                        @NotNull PlanKey branchKey)
        Count versions related to deployment project and a specified plan branch
        Parameters:
        deploymentProjectId - id of deployment project
        branchKey - plan branch key
        Returns:
        number of versions created in deployment project
        Since:
        7.0

      • getDeploymentProjectVersionsNoVariables

        @NotNull
@NotNull List<DeploymentVersion> getDeploymentProjectVersionsNoVariables​(@NotNull
                                                                         @NotNull DeploymentProject deploymentProject)
        Retrieves the list of all the version for the deployment project, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts)
        Parameters:
        deploymentProject - deployment project
        Returns:
        all the versions for the specified deployment project. Empty list if deployment project not found or if there is no versions for it.

      • getDeploymentProjectVersionsNoVariables

        @NotNull
@NotNull List<DeploymentVersion> getDeploymentProjectVersionsNoVariables​(@NotNull
                                                                         @NotNull DeploymentProject deploymentProject,
                                                                         int offset,
                                                                         int maxResults)
        Retrieves the list of the version for the deployment project, sorted by CreationDate (the most recent Deployment Versions will be returned as firsts).
        Parameters:
        deploymentProject - deployment project
        offset - number of results to skip
        maxResults - maximum length of the returned list
        Returns:
        the versions for the specified deployment project. Empty list if deployment project not found or if there is no versions for it.

      • getLatestVersionForProject

        @Deprecated
@Nullable
@Nullable DeploymentVersion getLatestVersionForProject​(long deploymentProjectId)
        Deprecated.
        since 5.1 use getLatestVersionForProject(long, PlanKey)
        Find the latest version for a deployment project regardless of branch used to create it. Comparison based on creation date.
        Parameters:
        deploymentProjectId - of the deployment project
        Returns:
        the latest version for a deployment project

      • getLatestVersionForProject

        @Nullable
@Nullable DeploymentVersion getLatestVersionForProject​(long deploymentProjectId,
                                                       @NotNull
                                                       @NotNull PlanKey branchKey)
        Find the latest version for a deployment project. Comparison based on creation date.
        Parameters:
        deploymentProjectId - of the deployment project
        branchKey - key of the PlanBranch
        Returns:
        the latest version created for a branch for a deployment project

      • getVersionArtifacts

        @NotNull
@NotNull com.google.common.collect.Multimap<String,​Artifact> getVersionArtifacts​(@NotNull
                                                                                       @NotNull DeploymentVersion deploymentVersion)
        Find all Artifact related to a version.
        Parameters:
        deploymentVersion -
        Returns:

      • getRelatedVersion

        @Nullable
@Nullable DeploymentVersion getRelatedVersion​(long deploymentProjectId,
                                              @NotNull
                                              @NotNull PlanResultKey planResultKey)
        Find latest version of a deployment project that is related to specific plan result.
        Parameters:
        deploymentProjectId -
        planResultKey -
        Returns:

      • findNextVersionContainingResult

        DeploymentVersion findNextVersionContainingResult​(long deploymentProjectId,
                                                  @NotNull
                                                  @NotNull PlanResultKey planResultKey)
        Find the first version that is created from a result which is later than current result (not taking custom revision into account)
        Parameters:
        deploymentProjectId -
        planResultKey -
        Returns:

      • getPossibleVersionVariables

        @NotNull
@NotNull Map<String,​VariableDefinitionContext> getPossibleVersionVariables​(@NotNull
                                                                                 @NotNull ImmutablePlan linkedPlan,
                                                                                 boolean includeUndeterminable)
        Provides a map of variables which might show up on a version.
        Parameters:
        linkedPlan - plan the deployment project is linked to
        includeUndeterminable - if true include variables that we don't currently know the value, with a nice example (used for display purposes)
        Returns:
        a map of variables which might show up on a version.

      • getPossibleVersionVariables

        @NotNull
@NotNull Map<String,​VariableDefinitionContext> getPossibleVersionVariables​(@NotNull
                                                                                 @NotNull ImmutablePlan linkedPlan,
                                                                                 @Nullable
                                                                                 @Nullable PlanResultKey planResultKey,
                                                                                 boolean includeUndeterminable)
        Provides a map of variables which might show up on a version.
        Parameters:
        linkedPlan - plan the deployment project is linked to
        planResultKey - resultKey for result variables context
        includeUndeterminable - if true include variables that we don't currently know the value, with a nice example (used for display purposes)
        Returns:
        a map of variables which might show up on a version.

      • getIncrementedVersionName

        @NotNull
@NotNull String getIncrementedVersionName​(@NotNull
                                          @NotNull String versionName)
        Calculates an increment of a version name. Increments last number in the name. If nothing found to increment will return passed in value.
        Parameters:
        versionName - to increment
        Returns:
        incremented version name.

      • updatePlanKey

        void updatePlanKey​(@NotNull
                   @NotNull PlanKey originalPlanKey,
                   @NotNull
                   @NotNull PlanKey newPlanKey)
        Update planKey in DeploymentVersion's related entities when plan key has changed (ie after moving plan)
        Parameters:
        originalPlanKey - original PlanKey
        newPlanKey - new PlanKey

      • findVersionsAssociatedWithJiraIssue

        @NotNull
@NotNull List<DeploymentVersion> findVersionsAssociatedWithJiraIssue​(long deploymentProjectId,
                                                                     @NotNull
                                                                     @NotNull String issueKey)
        Find all the versions of a DeploymentProject that are associated with a JIRA issue
        Parameters:
        deploymentProjectId -
        issueKey -
        Since:
        5.1

      • findVersionsAssociatedWithJiraIssue

        @NotNull
@NotNull com.google.common.collect.Multimap<DeploymentProject,​DeploymentVersion> findVersionsAssociatedWithJiraIssue​(@NotNull
                                                                                                                           @NotNull String issueKey)
        Find all the version that are associated with a JIRA issue, grouped by DeploymentProject
        Parameters:
        issueKey -
        Since:
        5.1

      • findVersionIdentifiersAssociatedWithJiraIssue

        @Internal
@NotNull
@NotNull com.google.common.collect.Multimap<DeploymentProject,​Pair<Long,​PlanResultKey>> findVersionIdentifiersAssociatedWithJiraIssue​(@NotNull
                                                                                                                                                  @NotNull String issueKey)
        Find all the version identifiers that are associated with a JIRA issue, grouped by DeploymentProject Note: this API is in its intermittent form and is subject to change.
        Parameters:
        issueKey -
        Since:
        9.3

      • findLatestKnownVersionsForEnvironmentsOfDeploymentProject

        @NotNull
@NotNull Map<DeploymentVersion,​Integer> findLatestKnownVersionsForEnvironmentsOfDeploymentProject​(DeploymentProject deploymentProject)
        Find all DeploymentVersion that are currently deployed on environments of a DeploymentProject For each version found give number of environments it is present on.
        Parameters:
        deploymentProject -
        Returns:
        Since:
        5.1

      • hasVersionsUnrelatedToBranch

        boolean hasVersionsUnrelatedToBranch​(long deploymentProjectId,
                                     @NotNull
                                     @NotNull PlanKey branchKey)
        Test if there are DeploymentVersions in a DeploymentProject that are unrelated to given branch
        Parameters:
        deploymentProjectId - identifies deployment project
        branchKey - key of the branch
        Returns:
        true if there are versions in the project that are unrelated to branch
        Since:
        5.2

      • getVariableContextForVersion

        @NotNull
@NotNull com.google.common.collect.ImmutableList<VariableSubstitutionContext> getVariableContextForVersion​(@NotNull
                                                                                                           @org.jetbrains.annotations.NotNull long deploymentVersionId)
        Fetch variable context associated with a version.
        Since:
        6.8.1

      • getVersionNamePreview

        String getVersionNamePreview​(ResultsSummary resultsSummary,
                             String versionName)
        Given a version name and a result summary, what would the version name look like after substitution. Does not check/mutate for uniqueness.
        Parameters:
        resultsSummary - the version would get created from
        versionName - the potential name of the version
        Returns:
        substituted version name

      • resetVersionsAge

        void resetVersionsAge​(@NotNull
                      @NotNull DeploymentVersion deploymentVersion)
        Resets version's age to 0.
        Since:
        5.7

      • getLatestVersionStatuses

        @Deprecated
@NotNull
@NotNull Map<Long,​DeploymentVersionStatus> getLatestVersionStatuses​(@NotNull
                                                                          @NotNull List<Long> deploymentVersionIds)
        Deprecated.
        since 9.4 use #getAllUsersLatestVersionStatusesOrderedByCreationDate(List) instead
        Find a latest version status for each version id. If no version status is available, the resulting map will not contain corresponding entry.
        Parameters:
        deploymentVersionIds -
        Since:
        6.8

      • getAllUsersLatestVersionStatusesOrderedByCreationDate

        @NotNull
@NotNull Map<Long,​List<DeploymentVersionStatus>> getAllUsersLatestVersionStatusesOrderedByCreationDate​(@NotNull
                                                                                                             @NotNull List<Long> deploymentVersionIds)
        Find all users' latest version statuses for each version id ordered by creation date. If no version status is available, the resulting map will contain empty list.
        Parameters:
        deploymentVersionIds -
        Since:
        9.4

      • updateVersionsForResult

        void updateVersionsForResult​(@NotNull
                             @NotNull PlanResultKey planResultKey)
        Update related versions data (artifacts and variables) after a chain stage has been completed.