com.atlassian.bamboo.deployments.projects.service

Interface DeploymentProjectService

All Known Implementing Classes:

DeploymentProjectServiceImpl

@PublicApi
public interface DeploymentProjectService

Service to provide access to all things Deployment Project, And Project Item.

Method Summary

Modifier and Type	Method and Description
void	addArtifactProjectItem(long deploymentProjectId, ArtifactDefinition artifactDefinition) Add artifact project item to deployment project.
default DeploymentProject	addDeploymentProject(String name, String description, String planKeyString) Create a new deployment project.
DeploymentProject	addDeploymentProject(String name, String description, String planKeyString, boolean accessForAllUsers) Create a new deployment project.
DeploymentProject	cloneDeploymentProject(long id, String name, String description, String planKeyString) Create a new deployment project.
void	deleteDeploymentProject(long deploymentProjectId) Deprecated. since 5.4 use DeploymentProjectDeletionService.deleteDeploymentProject(long)
DeploymentProject	editDeploymentProject(long deploymentProjectId, String name, String description, String planKeyString) Edit the details of the deployment project
Collection<Long>	findDeploymentProjectsInOtherStates(VcsLocationBambooSpecsState specsState)
Map<String,ArtifactDefinition>	generateArtifactProjectItems(MutableDeploymentProject mutableDeploymentProject) Create and save artifact project items for deployment projects.
List<DeploymentProject>	getAllDeploymentProjects()
DeploymentProject	getDeploymentProject(long id)
int	getDeploymentProjectCount()
DeploymentProject	getDeploymentProjectForEnvironment(long environmentID) Retrieve the deployment project that a specific environment belongs to.
DeploymentProject	getDeploymentProjectForVersion(long versionId) Retrieve the deployment project that a specific version belongs to.
List<DeploymentProjectItem>	getDeploymentProjectItems(long deploymentProjectId) Does not validate deployment project exists
List<DeploymentProject>	getDeploymentProjectsReferencingArtifact(Artifact artifact) Get all deployment projects that contain a version that uses specified artifact
List<DeploymentProject>	getDeploymentProjectsRelatedToArtifact(ArtifactDefinition artifactDefinition) Retrieve the deployment projects that refer to the artifactDefinition within their items
List<DeploymentProject>	getDeploymentProjectsRelatedToPlan(PlanKey planKey) Retrieve the deployment projects that are linked to a specific plan
List<DeploymentProject>	getDeploymentProjectsRelatedToPlanConfiguration(PlanKey masterOrBranchPlanKey) Retrieve the deployment projects that are linked to a specific plan configuration, taking branch divergency into account.
List<DeploymentProject>	getDeploymentProjectsRelatedToPlanOrBranches(PlanKey masterOrBranchPlanKey) Retrieve the deployment projects that are linked to a specific plan or any of its branches.
List<DeploymentProjectWithEnvironmentStatuses>	getDeploymentProjectsWithStatusesRelatedToPlan(PlanKey planKey) Retrieve the deployment projects that are linked to a specific plan.
List<DeploymentProjectWithEnvironmentStatuses>	getDeploymentProjectsWithStatusesRelatedToPlanOrBranches(PlanKey masterOrBranchPlanKey) Retrieve the deployment projects that are linked to a specific plan or any of its branches.
List<DeploymentProjectStatusForResultSummary>	getDeploymentProjectsWithStatusesRelatedToPlanResult(ResultsSummary resultsSummary) Retrieve the deployment projects that are linked to a specific result.
String	getIncrementedVersionName(String versionName) Calculates an incremented version name for a project.
DeploymentProjectWithEnvironmentForDashboard	getPaginatedDeploymentsWithEnvironments(int start, int limit, String filter) Retrieve paginated view of DeploymentProject and Environment and information if there are more entries ordered by InternalDeploymentProject.getName() and InternalEnvironment.getPosition().
DeploymentProjectItem	getProjectItem(long projectItemId) Get a specific Project Item.
VersionNamingScheme	getVersionNamingScheme(long deploymentProjectId) Get the version naming configuration for a project
void	removeArtifactProjectItem(long deploymentProjectId, ArtifactDefinition artifactDefinition) Remove artifact project item from deployment project.
void	removeProjectItem(long deploymentProjectId, long projectItemId) Remove item from deployment project
void	resetTriggers(PlanKey planKey) Delete and recreate the triggers for every deployment that's related to this planKey.
void	unlinkDeploymentProjectsRelatedToPlan(PlanKey planKey) Remove all references to a Plan from all related deployment projects.
void	updatePlanKey(PlanKey originalPlanKey, PlanKey newPlanKey) Update planKey in DeploymentProject when plan key has changed (ie after moving plan).
VersionNamingScheme	updateVersionNamingScheme(long deploymentProjectId, String nextVersionName, boolean autoIncrement, boolean applicableToBranches, Set<String> variablesToAutoIncrement) update the version naming configuration for a project
VersionNamingScheme	updateVersionNamingScheme(long deploymentProjectId, String nextVersionName, boolean autoIncrement, Set<String> variablesToAutoIncrement) Deprecated. since 6.0 use updateVersionNamingScheme(long, String, boolean, boolean, Set)
boolean	userHasPermissionsToChangeAutoIncrementedVariables(long deploymentProjectId, Set<String> variablesToAutoIncrement) Check if current user has necessary permissions to modify auto incremented variables settings.
ErrorCollection	validateAddDeploymentProject(String name, String description, String planKeyString) Validates data to be used when adding a deployment project.
ErrorCollection	validateAddDeploymentProject(String name, String description, String masterPlanKeyString, String planKeyString) Validates data to be used when adding a deployment project.
ErrorCollection	validateArtifactTaskDefinitionOnPlanChange(long deploymentProjectId, String planKeyString, Map<String,ArtifactValidationError> artifactValidationErrors) Validates artifact definitions on plan change and warn if artifact differ, so deployment tasks using it may fail
ErrorCollection	validateCloneDeploymentProject(String name, String description, String planKeyString) Validates data to be used when adding a deployment project.
ErrorCollection	validateEditDeploymentProject(long id, String name, String description, String planKeyString) Validates data to be used when editing an existing deployment.
ErrorCollection	validateEditDeploymentProject(long id, String name, String description, String masterPlanKeyString, String planKeyString) Validates data to be used when editing an existing deployment.
ErrorCollection	validateTriggerConfigurationOnPlanChange(long deploymentProjectId, PlanKey newPlanKey, List<EnvironmentTriggerValidationError> triggerValidationErrors) Validate trigger configuration on deployment project's plan change
ErrorCollection	validateVersionNamingScheme(long deploymentProjectId, String nextVersionName, boolean autoIncrement, Set<String> variablesToAutoIncrement) Validate the version naming configuration for a project

Method Detail

getAllDeploymentProjects

@NotNull
List<DeploymentProject> getAllDeploymentProjects()

Returns:

a list of all deployment projects

getDeploymentProjectsRelatedToPlan

@NotNull
List<DeploymentProject> getDeploymentProjectsRelatedToPlan(@NotNull
                                                                    PlanKey planKey)

Retrieve the deployment projects that are linked to a specific plan

Parameters:

planKey - of the linked plan

Returns:

a list of all deployment projects linked to a specified plan

getDeploymentProjectsRelatedToPlanOrBranches

@NotNull
List<DeploymentProject> getDeploymentProjectsRelatedToPlanOrBranches(@NotNull
                                                                              PlanKey masterOrBranchPlanKey)

Retrieve the deployment projects that are linked to a specific plan or any of its branches. Use with care: it will include the whole 'family', including deployments related to divergent branches. See also: getDeploymentProjectsRelatedToPlanConfiguration(PlanKey)

Parameters:

masterOrBranchPlanKey - identifies master plan or branch

Returns:

a list of all deployment projects linked to a specified plan or any of its branches

getDeploymentProjectsRelatedToPlanConfiguration

@NotNull
List<DeploymentProject> getDeploymentProjectsRelatedToPlanConfiguration(@NotNull
                                                                                 PlanKey masterOrBranchPlanKey)

Retrieve the deployment projects that are linked to a specific plan configuration, taking branch divergency into account. If the argument is a master plan or a lightweight branch, deployments linked to the master plan and lightweight branches are returned. If the argument is a divergent branch, only deployments linked to that particular branch will be returned.

Parameters:

masterOrBranchPlanKey - identifies master plan or branch

Returns:

a list of all deployment projects linked to a specified plan or any of its branches

Since:

7.0.5

getDeploymentProjectsWithStatusesRelatedToPlan

@NotNull
List<DeploymentProjectWithEnvironmentStatuses> getDeploymentProjectsWithStatusesRelatedToPlan(@NotNull
                                                                                                       PlanKey planKey)

Retrieve the deployment projects that are linked to a specific plan. Includes projects their environments + latest status

Parameters:

planKey - of the linked plan

Returns:

a list of all deployment projects linked to a specified plan

getDeploymentProjectsWithStatusesRelatedToPlanOrBranches

@NotNull
List<DeploymentProjectWithEnvironmentStatuses> getDeploymentProjectsWithStatusesRelatedToPlanOrBranches(@NotNull
                                                                                                                 PlanKey masterOrBranchPlanKey)

Retrieve the deployment projects that are linked to a specific plan or any of its branches. Includes projects their environments + latest status

Parameters:

masterOrBranchPlanKey - identifies master plan or branch

Returns:

a list of all deployment projects linked to a specified plan or any of its branches

getDeploymentProjectsWithStatusesRelatedToPlanResult

@NotNull
List<DeploymentProjectStatusForResultSummary> getDeploymentProjectsWithStatusesRelatedToPlanResult(@NotNull
                                                                                                            ResultsSummary resultsSummary)

Retrieve the deployment projects that are linked to a specific result. Includes projects their environments + latest status

Parameters:

resultsSummary - of the linked plan

Returns:

a list of all deployment projects linked to a specified plan

getDeploymentProjectsRelatedToArtifact

@NotNull
List<DeploymentProject> getDeploymentProjectsRelatedToArtifact(@NotNull
                                                                        ArtifactDefinition artifactDefinition)

Retrieve the deployment projects that refer to the artifactDefinition within their items

Parameters:

artifactDefinition - related artifact definition

Returns:

a list of all deployment projects referring specified artifactDefinition

getDeploymentProject

@Nullable
DeploymentProject getDeploymentProject(long id)
                                          throws org.acegisecurity.AccessDeniedException

Parameters:

id - of the deployment project to retrieve

Returns:

deployment project with the given id or null if none found.

Throws:

org.acegisecurity.AccessDeniedException

getDeploymentProjectForEnvironment

@Nullable
DeploymentProject getDeploymentProjectForEnvironment(long environmentID)

Retrieve the deployment project that a specific environment belongs to.

Parameters:

environmentID - of the environment

Returns:

DeploymentProject environment belongs to

getDeploymentProjectForVersion

@Nullable
DeploymentProject getDeploymentProjectForVersion(long versionId)

Retrieve the deployment project that a specific version belongs to.

Parameters:

versionId - of the version

Returns:

DeploymentProject version belongs to

deleteDeploymentProject

@Deprecated
void deleteDeploymentProject(long deploymentProjectId)

Deprecated. since 5.4 use DeploymentProjectDeletionService.deleteDeploymentProject(long)

Delete DeploymentProject and all dependent data

Parameters:

deploymentProjectId - of the project

validateAddDeploymentProject

@NotNull
ErrorCollection validateAddDeploymentProject(String name,
                                                      String description,
                                                      String planKeyString)

Validates data to be used when adding a deployment project. This method is used by automated deployment project creation where validation of master plan is not required.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

planKeyString - key of the linked plan or its branch

Returns:

ErrorCollection containing any errors which may exist. If no errors found and empty ErrorCollection will be returned;

validateAddDeploymentProject

@NotNull
ErrorCollection validateAddDeploymentProject(String name,
                                                      String description,
                                                      String masterPlanKeyString,
                                                      String planKeyString)

Validates data to be used when adding a deployment project. This method is used by UI where validation of master plan is required.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

masterPlanKeyString - key of the master of linked plan/branch

planKeyString - key of the linked plan or its branch

Returns:

ErrorCollection containing any errors which may exist. If no errors found and empty ErrorCollection will be returned;

addDeploymentProject

@NotNull
default DeploymentProject addDeploymentProject(String name,
                                                        String description,
                                                        String planKeyString)
                                                 throws WebValidationException

Create a new deployment project.

Allows all Bamboo users to access the newly created deployment project. To create a deployment project with restricted initial access, use addDeploymentProject(String, String, String, boolean) instead.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

planKeyString - key of the linked plan or its branch

Returns:

the created deployment project.

Throws:

WebValidationException

addDeploymentProject

@NotNull
DeploymentProject addDeploymentProject(String name,
                                                String description,
                                                String planKeyString,
                                                boolean accessForAllUsers)
                                         throws WebValidationException

Create a new deployment project.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

planKeyString - key of the linked plan or its branch

accessForAllUsers - whether all Bamboo users will be allowed to view the deployment project

Returns:

the created deployment project.

Throws:

WebValidationException

validateCloneDeploymentProject

@NotNull
ErrorCollection validateCloneDeploymentProject(String name,
                                                        String description,
                                                        String planKeyString)

Validates data to be used when adding a deployment project. This method is used by UI where validation of master plan is required.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

Returns:

ErrorCollection containing any errors which may exist. If no errors found and empty ErrorCollection will be returned;

cloneDeploymentProject

@NotNull
DeploymentProject cloneDeploymentProject(long id,
                                                  String name,
                                                  String description,
                                                  String planKeyString)
                                           throws WebValidationException

Create a new deployment project.

Parameters:

name - shortish display name of the project

description - optional description of what the project is about

Returns:

the created deployment project.

Throws:

WebValidationException

validateEditDeploymentProject

@NotNull
ErrorCollection validateEditDeploymentProject(long id,
                                                       String name,
                                                       @Nullable
                                                       String description,
                                                       @Nullable
                                                       String planKeyString)

Validates data to be used when editing an existing deployment. This method is used by automated deployment project edit where validation of master plan is not required.

Parameters:

id -

name -

description -

planKeyString -

Returns:

ErrorCollection containing any errors which may exist. If no errors found and empty ErrorCollection will be returned;

validateEditDeploymentProject

@NotNull
ErrorCollection validateEditDeploymentProject(long id,
                                                       String name,
                                                       String description,
                                                       String masterPlanKeyString,
                                                       String planKeyString)

Validates data to be used when editing an existing deployment. This method is used by UI where validation of master plan is required.

Parameters:

id -

name -

description -

masterPlanKeyString -

planKeyString -

Returns:

ErrorCollection containing any errors which may exist. If no errors found and empty ErrorCollection will be returned;

validateArtifactTaskDefinitionOnPlanChange

@NotNull
ErrorCollection validateArtifactTaskDefinitionOnPlanChange(long deploymentProjectId,
                                                                    String planKeyString,
                                                                    @NotNull
                                                                    Map<String,ArtifactValidationError> artifactValidationErrors)

Validates artifact definitions on plan change and warn if artifact differ, so deployment tasks using it may fail

Parameters:

deploymentProjectId -

planKeyString -

Returns:

validateTriggerConfigurationOnPlanChange

@NotNull
ErrorCollection validateTriggerConfigurationOnPlanChange(long deploymentProjectId,
                                                                  @NotNull
                                                                  PlanKey newPlanKey,
                                                                  @NotNull
                                                                  List<EnvironmentTriggerValidationError> triggerValidationErrors)

Validate trigger configuration on deployment project's plan change

Parameters:

deploymentProjectId - identifies deployment project

newPlanKey - new plan key

triggerValidationErrors - list to store trigger validation errors

Returns:

editDeploymentProject

@NotNull
DeploymentProject editDeploymentProject(long deploymentProjectId,
                                                 String name,
                                                 @Nullable
                                                 String description,
                                                 String planKeyString)
                                          throws WebValidationException

Edit the details of the deployment project

Parameters:

deploymentProjectId - of the deployment project to edit

name - the new name for the project

description - the new description of the project

planKeyString - optional of the linked plan

Returns:

The updated deployment project

Throws:

WebValidationException

getDeploymentProjectItems

@NotNull
List<DeploymentProjectItem> getDeploymentProjectItems(long deploymentProjectId)

Does not validate deployment project exists

Parameters:

deploymentProjectId - if of the deployment project

Returns:

all project items for the specified deployment project. Empty list if deployment project not found.

getProjectItem

@Nullable
DeploymentProjectItem getProjectItem(long projectItemId)

Get a specific Project Item.

Parameters:

projectItemId - of the project item to retrieve.

Returns:

project item with the given idea. Null if none found.

addArtifactProjectItem

void addArtifactProjectItem(long deploymentProjectId,
                            @NotNull
                            ArtifactDefinition artifactDefinition)

Add artifact project item to deployment project. If artifact is already referenced by one of the project items this method will do nothing. There's no check if artifact is "shared".

Parameters:

deploymentProjectId - id of the deployment project

artifactDefinition - ArtifactDefinition

Throws:

IllegalArgumentException - when DeploymentProject doesn't exist

removeArtifactProjectItem

void removeArtifactProjectItem(long deploymentProjectId,
                               @NotNull
                               ArtifactDefinition artifactDefinition)

Remove artifact project item from deployment project. If artifact is not referenced by any of the project items this method will do nothing.

Parameters:

deploymentProjectId - id of the deployment project

artifactDefinition - ArtifactDefinition

removeProjectItem

void removeProjectItem(long deploymentProjectId,
                       long projectItemId)

Remove item from deployment project

Parameters:

deploymentProjectId - DeploymentProject id

projectItemId -

getVersionNamingScheme

@Nullable
VersionNamingScheme getVersionNamingScheme(long deploymentProjectId)

Get the version naming configuration for a project

Parameters:

deploymentProjectId - of the project

Returns:

version naming scheme for a project

getIncrementedVersionName

@NotNull
String getIncrementedVersionName(@NotNull
                                          String versionName)

Calculates an incremented version name for a project. See VersionNamingService.getIncrementedVersionName for details.

Parameters:

versionName - to increment

Returns:

incremented version name.

userHasPermissionsToChangeAutoIncrementedVariables

boolean userHasPermissionsToChangeAutoIncrementedVariables(long deploymentProjectId,
                                                           @NotNull
                                                           Set<String> variablesToAutoIncrement)

Check if current user has necessary permissions to modify auto incremented variables settings.

Parameters:

deploymentProjectId -

variablesToAutoIncrement -

Since:

6.1

validateVersionNamingScheme

@NotNull
ErrorCollection validateVersionNamingScheme(long deploymentProjectId,
                                                     String nextVersionName,
                                                     boolean autoIncrement,
                                                     @NotNull
                                                     Set<String> variablesToAutoIncrement)

Validate the version naming configuration for a project

Parameters:

deploymentProjectId - of the project

nextVersionName - the value to be used for the next version name

autoIncrement - whether the version name should be auto-incremented

variablesToAutoIncrement - variables to increment

Returns:

error collection with any validation errors, if no errors, empty error collection is returned

updateVersionNamingScheme

@Deprecated
 @NotNull
VersionNamingScheme updateVersionNamingScheme(long deploymentProjectId,
                                                                    String nextVersionName,
                                                                    boolean autoIncrement,
                                                                    @NotNull
                                                                    Set<String> variablesToAutoIncrement)
                                                             throws WebValidationException

Deprecated. since 6.0 use updateVersionNamingScheme(long, String, boolean, boolean, Set)

update the version naming configuration for a project

Parameters:

deploymentProjectId - of the project

nextVersionName - the value to be used for the next version name

autoIncrement - whether the version name should be auto-incremented

variablesToAutoIncrement - variables to increment

Returns:

the updated version naming scheme.

Throws:

WebValidationException - if any validation errors occur

updateVersionNamingScheme

@NotNull
VersionNamingScheme updateVersionNamingScheme(long deploymentProjectId,
                                                       String nextVersionName,
                                                       boolean autoIncrement,
                                                       boolean applicableToBranches,
                                                       @NotNull
                                                       Set<String> variablesToAutoIncrement)
                                                throws WebValidationException

update the version naming configuration for a project

Parameters:

deploymentProjectId - of the project

nextVersionName - the value to be used for the next version name

autoIncrement - whether the version name should be auto-incremented

applicableToBranches - whether the same scheme should be used with branches

variablesToAutoIncrement - variables to increment

Returns:

the updated version naming scheme.

Throws:

WebValidationException - if any validation errors occur

unlinkDeploymentProjectsRelatedToPlan

void unlinkDeploymentProjectsRelatedToPlan(@NotNull
                                           PlanKey planKey)

Remove all references to a Plan from all related deployment projects.

Parameters:

planKey -

getDeploymentProjectsReferencingArtifact

List<DeploymentProject> getDeploymentProjectsReferencingArtifact(@NotNull
                                                                 Artifact artifact)

Get all deployment projects that contain a version that uses specified artifact

Parameters:

artifact -

Returns:

updatePlanKey

void updatePlanKey(@NotNull
                   PlanKey originalPlanKey,
                   @NotNull
                   PlanKey newPlanKey)

Update planKey in DeploymentProject when plan key has changed (ie after moving plan).

Parameters:

originalPlanKey - original PlanKey

newPlanKey - new PlanKey

resetTriggers

void resetTriggers(@NotNull
                   PlanKey planKey)

Delete and recreate the triggers for every deployment that's related to this planKey.

Parameters:

planKey -

getDeploymentProjectCount

int getDeploymentProjectCount()

Returns:

count of all deployment projects

generateArtifactProjectItems

Map<String,ArtifactDefinition> generateArtifactProjectItems(@NotNull
                                                            MutableDeploymentProject mutableDeploymentProject)

Create and save artifact project items for deployment projects.

Since:

6.1

findDeploymentProjectsInOtherStates

@NotNull
Collection<Long> findDeploymentProjectsInOtherStates(@NotNull
                                                              VcsLocationBambooSpecsState specsState)

getPaginatedDeploymentsWithEnvironments

DeploymentProjectWithEnvironmentForDashboard getPaginatedDeploymentsWithEnvironments(int start,
                                                                                     int limit,
                                                                                     @Nullable
                                                                                     String filter)

Retrieve paginated view of DeploymentProject and Environment and information if there are more entries ordered by InternalDeploymentProject.getName() and InternalEnvironment.getPosition(). Deployment projects are not operation aware, environments are. In case of null or empty filter no filtering.

Since:

6.8