com.atlassian.bamboo.plan

Interface PlanManager

All Known Implementing Classes:

PlanManagerImpl

@PublicApi
public interface PlanManager

Manager for all Plan types within Bamboo

Use this manager if you need to address Builds, Plans, etc.

Since:

2.7

Method Summary

Modifier and Type	Method and Description
boolean	assertPlanPermission(PlanIdentifier plan) Used to validate user permission for plan.
void	createPlan(Plan plan) Same as savePlan, but create permissions used instead of edit permissions.
void	deletePlan(Plan plan) Removes the plan object from the database.
Set<ImmutableChain>	filterFavouritedPlans(Collection<? extends ImmutableChain> plans, com.atlassian.user.User user) Return a set of Plans that are a subset of the given TopLevelPlans collection that are favourited by the User.
List<Chain>	getAllChainsAndJobsUnrestricted() WARNING this is probably a bad idea from a performance perspective, only do this if you're going to traverse through all the ChainStage and Job of all Chains returned.
<T extends Plan> List<PlanKey>	getAllPlanKeys(Class<T> planType) Deprecated. since 6.2 with no replacement
List<TopLevelPlan>	getAllPlans() Deprecated. since 5.0 please use CachedPlanManager
<T extends Plan> List<T>	getAllPlans(Class<T> planType) Returns all Plan's filtered by Class.
<T extends Plan> List<T>	getAllPlans(Class<T> planType, int firstResult, int maxResults) Returns all Plan's filtered by Class.
<T extends Plan> List<T>	getAllPlansByProject(Project project, Class<T> planType) Returns all Plan's filtered by Project and Class, including the plans marked for deletion.
<T extends Plan> Collection<T>	getAllPlansMarkedForDeletion(Class<T> planType) Returns a list of Plans that are ImmutableDeletable.isMarkedForDeletion() for the given type
List<TopLevelPlan>	getAllPlansUnrestricted() Returns all TopLevelPlan's ignoring permissions
Set<ImmutableChain>	getFavouritePlans(com.atlassian.user.User user)
Set<Long>	getFavouritePlansIds(com.atlassian.user.User user) Return a collection of Favourite plan ids.
Plan	getPlanById(long id) Returns a Plan by its id
<T extends Plan> T	getPlanById(long id, Class<T> planType) Returns a Plan by its id and Class
Plan	getPlanByKey(PlanKey planKey) Returns a Plan by its PlanKey
<T extends Plan> T	getPlanByKey(PlanKey planKey, Class<T> planType) Returns a Plan by its PlanKey and Class
Plan	getPlanByKey(String planKey) Deprecated. since 4.2
<T extends Plan> T	getPlanByKey(String planKey, Class<T> planType) Deprecated. since 4.2
<T extends Plan> T	getPlanByKeyIfOfType(PlanKey planKey, Class<T> planType) Returns a Plan by its planKey and if it's of the type Class.
<T extends Plan> T	getPlanByOid(BambooEntityOid oid, Class<T> planType) Returns a Plan by its oid and Class
<T extends Plan> T	getPlanByPartialKeyAndName(PlanKey partialPlanKey, String planName, Class<T> planType) Deprecated. since 4.2
Class<? extends Plan>	getPlanClass(PlanKey planKey)
int	getPlanCount()
<T extends Plan> int	getPlanCount(Class<T> planType) How many plans filtered by Class currently exist
int	getPlanCount(ProjectIdentifier projectIdentifier) How many plans currently exist in a project.
PlanIdentifier	getPlanIdentifierForPermissionCheckingByKey(String planKey) Returns a Plan skeleton skeleton providing ONLY id and key, that matches the given key This method should be used only for permission checking using Acegi
<T extends Plan> List<PlanIdentifier>	getPlanIdentifiersForProject(ProjectIdentifier project, Class<T> planType, boolean includeMarkedForDeletion) Retrieve a list of plans for a given project.
List<TopLevelPlan>	getPlansByProject(Project project) Returns all TopLevelPlan's filtered by Project Result of this method is filtered by Acegi.
<T extends Plan> List<T>	getPlansByProject(Project project, Class<T> planType) Returns all Plan's filtered by Project and Class
<T extends Plan> Map<Project,Collection<T>>	getProjectPlanMap(Class<T> planType, boolean includeEmptyProjects) Return mapping of Project to Plan of given type
boolean	isChainNameConflicting(String projectKey, long planIdToIgnore, String planName) Verifies whether a Chain name is unique with the given project
boolean	isPlanCreationAllowed() Check whether or not a plan can be created or not (based on licensing etc)
boolean	isPlanKeyConflicting(PlanKey planKey) Verifies whether a Plan key is unique within whole Bamboo installation
boolean	isPlanKeyConflicting(PlanKey planKey, long planIdToIgnore) Verifies whether a Plan key is unique within whole Bamboo installation
void	markPlansForDeletion(PlanKey planKey) Efficiently marks a plan to be deleted
void	removeStages(PlanKey key, Collection<Long> stageIds) Remove the tages from the plan specified.
void	savePlan(Plan plan) Saves the Plan
void	savePlanWithSchedulesStopped(Plan plan) Saves the Plan while polling jobs are stopped.
void	setPlanSuspendedState(PlanKey planKey, boolean isSuspended)
void	syncDeletionStatusOfChainBranches() Performs a cleanup task to mark ChainBranch objects that have a master Plan that is marked to be deleted, but is not marked as deleted.
void	syncDeletionStatusOfJobs() Performs a cleanup task to mark Job objects that have a Plan or ChainStage that is marked to be deleted, but it itself was not marked as deleted.
void	triggerConfigUpdatedEventsForPlansInProject(Project project) Triggers updated events for every plan in a project regardless of permissions.

Method Detail

getPlanIdentifierForPermissionCheckingByKey

@Nullable
PlanIdentifier getPlanIdentifierForPermissionCheckingByKey(@NotNull
                                                                     String planKey)

Returns a Plan skeleton skeleton providing ONLY id and key, that matches the given key This method should be used only for permission checking using Acegi

If Job key is provided as a parameter, parent Chain will be returned anyway, as Acegi assertions are defined only for TopLevelPlans

Parameters:

planKey - of the plan to find

Returns:

plan by the id if found, otherwise null

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type (should never happen)

getPlanById

@Nullable
Plan getPlanById(long id)
                    throws IncorrectPlanTypeException

Returns a Plan by its id

Parameters:

id - of the plan

Returns:

plan with the given id, null if it doesn't exist

Throws:

IncorrectPlanTypeException - if plan cannot be found

getPlanById

@Nullable
<T extends Plan> T getPlanById(long id,
                                         Class<T> planType)
                                  throws IncorrectPlanTypeException

Returns a Plan by its id and Class

Parameters:

id - of the plan

planType - - the type of the plan to retrieve

Returns:

plan with the given id, if found AND is of the correct type.

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type

getPlanByOid

@Nullable
<T extends Plan> T getPlanByOid(BambooEntityOid oid,
                                          Class<T> planType)
                                   throws IncorrectPlanTypeException

Returns a Plan by its oid and Class

Parameters:

oid - of the plan

planType - - the type of the plan to retrieve

Returns:

plan with the given oid, if found AND is of the correct type.

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type

getPlanByKey

@Nullable
Plan getPlanByKey(@NotNull
                            PlanKey planKey)
                     throws IncorrectPlanTypeException

Returns a Plan by its PlanKey

Parameters:

planKey - to search for

Returns:

plan

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type (should never happen)

getPlanByKey

@Nullable
<T extends Plan> T getPlanByKey(@NotNull
                                          PlanKey planKey,
                                          Class<T> planType)
                                   throws IncorrectPlanTypeException

Returns a Plan by its PlanKey and Class

Parameters:

planKey - to search for

planType - - the type of the plan to retrieve

Returns:

plan with the given key, if found AND is of the correct type.

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type

getPlanByKeyIfOfType

@Nullable
<T extends Plan> T getPlanByKeyIfOfType(@NotNull
                                                  PlanKey planKey,
                                                  @NotNull
                                                  Class<T> planType)

Returns a Plan by its planKey and if it's of the type Class. Does not throw IncorrectPlanTypeException. Should only be used when the type of the plan can not be known.

Parameters:

planKey - to search for

planType - the type of the plan to retrieve

Returns:

null if the plan doesn't exist, or it's not of the found type

getAllPlans

@NotNull
 @Deprecated
List<TopLevelPlan> getAllPlans()

Deprecated. since 5.0 please use CachedPlanManager

Returns all TopLevelPlan's

Returns:

plans

getAllPlansUnrestricted

List<TopLevelPlan> getAllPlansUnrestricted()

Returns all TopLevelPlan's ignoring permissions

Returns:

getAllPlans

@NotNull
<T extends Plan> List<T> getAllPlans(Class<T> planType)

Returns all Plan's filtered by Class. Does not include plans marked for deletion.

Parameters:

planType - - the type of the plan to retrieve

Returns:

plans sorted by DescriptionProvider.getName()

getAllPlanKeys

@NotNull
 @Deprecated
<T extends Plan> List<PlanKey> getAllPlanKeys(Class<T> planType)

Deprecated. since 6.2 with no replacement

Returns keys of all Plan's filtered by Class. Does not include plans marked for deletion.

Parameters:

planType - - the type of the plan to retrieve

Returns:

plan keys

getAllPlans

@NotNull
<T extends Plan> List<T> getAllPlans(Class<T> planType,
                                              int firstResult,
                                              int maxResults)

Returns all Plan's filtered by Class. Does not include plans marked for deletion.

Parameters:

planType - - the type of the plan to retrieve

firstResult - firstResult for a paginated results

maxResults - maximum number of results to return

Returns:

plans sorted by DescriptionProvider.getName()

getAllChainsAndJobsUnrestricted

@NotNull
List<Chain> getAllChainsAndJobsUnrestricted()

WARNING this is probably a bad idea from a performance perspective, only do this if you're going to traverse through all the ChainStage and Job of all Chains returned.

Returns:

getPlansByProject

@NotNull
List<TopLevelPlan> getPlansByProject(Project project)

Returns all TopLevelPlan's filtered by Project Result of this method is filtered by Acegi.

Parameters:

project - - that the plans will belong to

Returns:

TopLevelPlan plans contained within the given project

getPlansByProject

@NotNull
<T extends Plan> List<T> getPlansByProject(Project project,
                                                    Class<T> planType)

Returns all Plan's filtered by Project and Class

Parameters:

project - - that the plans will belong to

planType - - the type of the plan to retrieve

Returns:

plans contained within the given project and of the given type

getAllPlansByProject

@NotNull
<T extends Plan> List<T> getAllPlansByProject(Project project,
                                                       Class<T> planType)

Returns all Plan's filtered by Project and Class, including the plans marked for deletion.

Parameters:

project - - that the plans will belong to

planType - - the type of the plan to retrieve

Returns:

plans contained within the given project and of the given type

getProjectPlanMap

@NotNull
<T extends Plan> Map<Project,Collection<T>> getProjectPlanMap(Class<T> planType,
                                                                       boolean includeEmptyProjects)

Return mapping of Project to Plan of given type

Parameters:

planType - type of plan to be selected from DB

includeEmptyProjects - should empty projects be included in result

Returns:

mapping of Project to Plan of given type

getPlanIdentifiersForProject

@NotNull
<T extends Plan> List<PlanIdentifier> getPlanIdentifiersForProject(@NotNull
                                                                            ProjectIdentifier project,
                                                                            @NotNull
                                                                            Class<T> planType,
                                                                            boolean includeMarkedForDeletion)

Retrieve a list of plans for a given project. Only minimal data about the plans is returned.

Parameters:

project - to get plans for

planType - to filter plans by

includeMarkedForDeletion - set to true if you want to return plans marked for deletion

Returns:

PlanIdentifiers meeting the above criteria.

getFavouritePlans

Set<ImmutableChain> getFavouritePlans(@NotNull
                                      com.atlassian.user.User user)

getFavouritePlansIds

@NotNull
Set<Long> getFavouritePlansIds(@NotNull
                                        com.atlassian.user.User user)

Return a collection of Favourite plan ids.

Parameters:

user -

Returns:

favouritePlansIds

filterFavouritedPlans

@NotNull
Set<ImmutableChain> filterFavouritedPlans(@NotNull
                                                   Collection<? extends ImmutableChain> plans,
                                                   @NotNull
                                                   com.atlassian.user.User user)

Return a set of Plans that are a subset of the given TopLevelPlans collection that are favourited by the User. Plans are not filtered by read permission.

Parameters:

plans - to filter

user - to return the favourites of

Returns:

a set of Chains that are a subset of the given TopLevelPlans collection that are favourited by the User

getAllPlansMarkedForDeletion

@NotNull
<T extends Plan> Collection<T> getAllPlansMarkedForDeletion(Class<T> planType)

Returns a list of Plans that are ImmutableDeletable.isMarkedForDeletion() for the given type

Returns:

plansMarkedForDeletion

getPlanCount

int getPlanCount()

Returns:

How many Buildable's exists

getPlanCount

<T extends Plan> int getPlanCount(Class<T> planType)

How many plans filtered by Class currently exist

Parameters:

planType - - the type of the plan to retrieve

Returns:

how many plans exist in the datbase

getPlanCount

int getPlanCount(@NotNull
                 ProjectIdentifier projectIdentifier)

How many plans currently exist in a project.

Parameters:

projectIdentifier - identifier of the project

Returns:

number of plans in the project, excluding ones marked for deletion

isChainNameConflicting

boolean isChainNameConflicting(@NotNull
                               String projectKey,
                               long planIdToIgnore,
                               @NotNull
                               String planName)

Verifies whether a Chain name is unique with the given project

Parameters:

projectKey - of the project to look for the plan in

planIdToIgnore - the id of the plan that has to be ignored during lookup (when you're saving a Plan, you should supply the plan id here)

planName - - name of the plan inside the project: this is just the plan component of the name (i.e does not include the project component)

Returns:

true if the name is in conflict

Since:

4.0

isPlanKeyConflicting

boolean isPlanKeyConflicting(@NotNull
                             PlanKey planKey)

Verifies whether a Plan key is unique within whole Bamboo installation

Parameters:

planKey - key of the plan to be searched for in the database

Returns:

true if plan key is conflicting

Since:

4.3

isPlanKeyConflicting

boolean isPlanKeyConflicting(@NotNull
                             PlanKey planKey,
                             long planIdToIgnore)

Verifies whether a Plan key is unique within whole Bamboo installation

Parameters:

planKey -

planIdToIgnore - id of plan which we want to set key for, if the key is used by that plan, it's not really conflicting

Returns:

true if plan key is conflicting

Since:

5.15

getPlanByPartialKeyAndName

@Nullable
 @Deprecated
<T extends Plan> T getPlanByPartialKeyAndName(@NotNull
                                                                     PlanKey partialPlanKey,
                                                                     @NotNull
                                                                     String planName,
                                                                     Class<T> planType)
                                                              throws IncorrectPlanTypeException

Deprecated. since 4.2

Used for Job validation. Should update to be a specialised method

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type

getPlanClass

@Nullable
Class<? extends Plan> getPlanClass(@NotNull
                                             PlanKey planKey)

assertPlanPermission

boolean assertPlanPermission(@NotNull
                             PlanIdentifier plan)

Used to validate user permission for plan.

Parameters:

plan - to check the permissions of

Returns:

true if the current user has read(?) permissions on the plan

isPlanCreationAllowed

boolean isPlanCreationAllowed()

Check whether or not a plan can be created or not (based on licensing etc)

Returns:

true if a plan can be created otherwise false;

savePlan

void savePlan(@NotNull
              Plan plan)

Saves the Plan

Parameters:

plan - to be saved

savePlanWithSchedulesStopped

void savePlanWithSchedulesStopped(@NotNull
                                  Plan plan)

Saves the Plan while polling jobs are stopped.

Parameters:

plan -

Since:

5.0

setPlanSuspendedState

void setPlanSuspendedState(PlanKey planKey,
                           boolean isSuspended)

triggerConfigUpdatedEventsForPlansInProject

void triggerConfigUpdatedEventsForPlansInProject(@NotNull
                                                 Project project)

Triggers updated events for every plan in a project regardless of permissions.

Parameters:

project - to trigger event for.

createPlan

void createPlan(Plan plan)

Same as savePlan, but create permissions used instead of edit permissions.

deletePlan

void deletePlan(@NotNull
                Plan plan)

Removes the plan object from the database. Does not do any other clean up work at all Please use the DeletionService rather than using this method directly

Parameters:

plan - to delete.

markPlansForDeletion

void markPlansForDeletion(PlanKey planKey)

Efficiently marks a plan to be deleted

Parameters:

planKey -

syncDeletionStatusOfChainBranches

void syncDeletionStatusOfChainBranches()

Performs a cleanup task to mark ChainBranch objects that have a master Plan that is marked to be deleted, but is not marked as deleted.

syncDeletionStatusOfJobs

void syncDeletionStatusOfJobs()

Performs a cleanup task to mark Job objects that have a Plan or ChainStage that is marked to be deleted, but it itself was not marked as deleted.

removeStages

void removeStages(@NotNull
                  PlanKey key,
                  @NotNull
                  Collection<Long> stageIds)

Remove the tages from the plan specified. key must be for a Chain

Parameters:

key -

stageIds -

getPlanByKey

@Nullable
 @Deprecated
Plan getPlanByKey(@NotNull
                                         String planKey)
                                  throws IncorrectPlanTypeException

Deprecated. since 4.2

Returns a Plan by its planKey

Parameters:

planKey - of the plan to find

Returns:

plan by the id if found, otherwise null

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type (should never happen)

getPlanByKey

@Nullable
 @Deprecated
<T extends Plan> T getPlanByKey(@NotNull
                                                       String planKey,
                                                       Class<T> planType)
                                                throws IncorrectPlanTypeException

Deprecated. since 4.2

Returns a Plan by its planKey and Class

Parameters:

planKey - to search for

planType - - the type of the plan to retrieve

Returns:

plan with the given plan key, if found AND is of the correct type.

Throws:

IncorrectPlanTypeException - if plan cannot be found with the correct type