com.atlassian.bamboo.plan
Interface PlanManager

All Known Implementing Classes:
PlanManagerImpl

public interface PlanManager

Manager for all Plan types within Bamboo Use this manager if you need to address Builds, Plans, etc.


Method Summary
 boolean assertPlanPermission(Plan 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.
 java.util.Set<TopLevelPlan> filterFavouritedPlans(java.util.Collection<TopLevelPlan> plans, com.atlassian.user.User user)
          Return a set of Builds that are a subset of the given TopLevelPlans collection that are favourited by the User
 java.util.List<TopLevelPlan> getAllPlans()
          Returns all TopLevelPlan's
<T extends Plan>
java.util.List<T>
getAllPlans(java.lang.Class<T> planType)
          Returns all Plan's filtered by Class
<T extends Plan>
java.util.List<T>
getAllPlansByProject(Project project, java.lang.Class<T> planType)
          Returns all Plan's filtered by Project and Class, including the plans marked for deletion.
<T extends Plan>
java.util.List<T>
getAllPlansForClone(java.lang.Class<T> planType)
          Returns all Plan's filtered by Class Return list filtered to show only plans the current user is allowed to clone.
<T extends Plan>
java.util.Collection<T>
getAllPlansMarkedForDeletion(java.lang.Class<T> planType)
          Returns a list of Plans that are com.atlassian.bamboo.plan.Plan#markForDeletion() for the given type
 java.util.List<TopLevelPlan> getAllPlansUnrestricted()
          Returns all TopLevelPlan's ignoring permissions
 java.util.Set<TopLevelPlan> getFavouritePlans(com.atlassian.user.User user)
           
 Plan getPlanById(long id)
          Returns a Plan by its id
<T extends Plan>
T
getPlanById(long id, java.lang.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, java.lang.Class<T> planType)
          Returns a Plan by its PlanKey and Class
 Plan getPlanByKey(java.lang.String planKey)
          Returns a Plan by its planKey
<T extends Plan>
T
getPlanByKey(java.lang.String planKey, java.lang.Class<T> planType)
          Returns a Plan by its planKey and Class
<T extends Plan>
T
getPlanByKeyIfOfType(PlanKey planKey, java.lang.Class<T> planType)
          Returns a Plan by its planKey and if it's of the type Class.
<T extends Plan>
T
getPlanByKeyIfOfType(java.lang.String planKey, java.lang.Class<T> planType)
          Returns a Plan by its planKey and if it's of the type Class.
<T extends Plan>
T
getPlanByName(java.lang.String projectKey, java.lang.String planName, java.lang.Class<T> planType)
          Returns a Plan from a project with the given plan name and Class It is not possible to use this method if the planType parameter is a marker interface type such as Plan, Buildable or TopLevelPlan since it is possible to have a Chain and a Job that share the same name.
<T extends Plan>
T
getPlanByPartialKeyAndName(PlanKey partialPlanKey, java.lang.String planName, java.lang.Class<T> planType)
          Returns a Plan that matches the start of the given PlanKey and the full plan name
 Plan getPlanByResultKey(PlanResultKey planResultKey)
          Returns a Plan by a PlanResultKey
<T extends Plan>
T
getPlanByResultKey(PlanResultKey planResultKey, java.lang.Class<T> planType)
          Returns a Plan from a PlanResultKey and Class
 int getPlanCount()
           
<T extends Plan>
int
getPlanCount(java.lang.Class<T> planType)
          How many plans filtered by Class currently exist
 java.util.List<TopLevelPlan> getPlansByProject(Project project)
          Returns all TopLevelPlan's filtered by Project
<T extends Plan>
java.util.List<T>
getPlansByProject(Project project, java.lang.Class<T> planType)
          Returns all Plan's filtered by Project and Class
 Plan getPlanSkeletonForPermissionCheckingByKey(java.lang.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
<T extends Plan>
java.util.Map<Project,java.util.Collection<T>>
getProjectPlanMap(java.lang.Class<T> planType, boolean includeEmptyProjects)
          Return mapping of Project to Plan of given type
 boolean isPlanCreationAllowed()
          Check whether or not a plan can be created or not (based on licensing etc)
 java.util.Map<PlanKey,PlanKey> movePlanToProject(Plan plan, Project project, java.lang.String newPlanKey, java.lang.String newBuildName)
          Moves plan to a selected project.
<T extends Plan>
T
narrow(Plan plan, java.lang.Class<T> aClass)
          Deprecated. since 2.7 please use Narrow.to instead.
 java.lang.String revertVcsRevisionKey(java.lang.String buildKey, java.lang.String revisionForBuild, java.lang.String previousRevision)
          Revert lastVcsRevisionKey in build based on previous build revision contained in BuildContext.
 void savePlan(Plan plan)
          Saves the Plan
 void setPlanSuspendedState(Plan plan, boolean newState)
          Persists enable/disable state of a plan.
 void updateLatestVcsKey(Plan plan, java.lang.String vcsRevisionKey)
          Updates the build to the latest passed revision key
 void updateNamesAndDescription(java.lang.String projectName, java.lang.String buildName, java.lang.String description, Plan plan)
          Updates project and plan names and plan description.
 java.lang.String updateVcsRevisionKey(BuildContext buildContext)
          Updates lastVcsRevisionKey in build based on revision contained in BuildContext
 

Method Detail

narrow

@Deprecated
@Nullable
<T extends Plan> T narrow(@NotNull
                                              Plan plan,
                                              @NotNull
                                              java.lang.Class<T> aClass)
Deprecated. since 2.7 please use Narrow.to instead.

Converts the given Plan to the given Class Returns null if Plan could not be converted This method should only be used if testing the capability of a Plan where generically provided. For example, a perfectly acceptable use of #narrow(Plan,Class) may be where you are given a collection of Plans and you want to perform a specific operation on plans that are Buildable. In other cases (if possible) you should use one of the getPlanBy methods on this class instead of #narrow(Plan,Class).

Parameters:
plan - - to be narrowed
aClass - - type to be narrowed to
Returns:
plan or null
Throws:
IncorrectPlanTypeException - if plan cannot be found

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,
                                        java.lang.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

getPlanByKey

@Nullable
Plan getPlanByKey(@NotNull
                           java.lang.String planKey)
                  throws IncorrectPlanTypeException
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)

getPlanSkeletonForPermissionCheckingByKey

@Nullable
Plan getPlanSkeletonForPermissionCheckingByKey(@NotNull
                                                        java.lang.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)

getPlanByKey

@Nullable
<T extends Plan> T getPlanByKey(@NotNull
                                         java.lang.String planKey,
                                         java.lang.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 plan 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
                                                 java.lang.String planKey,
                                                 @NotNull
                                                 java.lang.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.

Type Parameters:
T -
Parameters:
planKey -
planType -
Returns:
null if the plan doesn't exist, or it's not of the found type

getPlanByKeyIfOfType

@Nullable
<T extends Plan> T getPlanByKeyIfOfType(@NotNull
                                                 PlanKey planKey,
                                                 @NotNull
                                                 java.lang.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

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)

assertPlanPermission

boolean assertPlanPermission(@NotNull
                             Plan 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

getPlanByKey

@Nullable
<T extends Plan> T getPlanByKey(@NotNull
                                         PlanKey planKey,
                                         java.lang.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

getPlanByResultKey

@Nullable
Plan getPlanByResultKey(@NotNull
                                 PlanResultKey planResultKey)
                        throws IncorrectPlanTypeException
Returns a Plan by a PlanResultKey

Parameters:
planResultKey - to look for the parent plan
Returns:
the parent plan for the given planResultKey
Throws:
IncorrectPlanTypeException - if plan cannot be found with the correct type (should never happen)

getPlanByResultKey

@Nullable
<T extends Plan> T getPlanByResultKey(@NotNull
                                               PlanResultKey planResultKey,
                                               java.lang.Class<T> planType)
                                  throws IncorrectPlanTypeException
Returns a Plan from a PlanResultKey and Class

Parameters:
planResultKey - to look for the parent plan
planType - - the type of the plan to retrieve
Returns:
parent plan for the given planResultKey, if found AND is of the correct type.
Throws:
IncorrectPlanTypeException - if plan cannot be found with the correct type

getPlanByName

@Nullable
<T extends Plan> T getPlanByName(@NotNull
                                          java.lang.String projectKey,
                                          @NotNull
                                          java.lang.String planName,
                                          java.lang.Class<T> planType)
                             throws IncorrectPlanTypeException
Returns a Plan from a project with the given plan name and Class It is not possible to use this method if the planType parameter is a marker interface type such as Plan, Buildable or TopLevelPlan since it is possible to have a Chain and a Job that share the same name.

Parameters:
projectKey - of the project to look for the plan in
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)
planType - - the type of the plan to retrieve
Returns:
plan with the given name and project key, if found AND is of the correct type.
Throws:
IncorrectPlanTypeException - if the result cannot be guaranteed to be unique

getPlanByPartialKeyAndName

@Nullable
<T extends Plan> T getPlanByPartialKeyAndName(@NotNull
                                                       PlanKey partialPlanKey,
                                                       @NotNull
                                                       java.lang.String planName,
                                                       java.lang.Class<T> planType)
                                          throws IncorrectPlanTypeException
Returns a Plan that matches the start of the given PlanKey and the full plan name

Parameters:
partialPlanKey - - the start of the plan key
planName - - name of the plan to search for: this is just the plan component of the name (i.e does not include the project component)
planType - - the type of the plan to retrieve
Returns:
plan with the given name, and partial key, if found AND is of the correct type
Throws:
IncorrectPlanTypeException - if plan cannot be found with the correct type

getAllPlans

@NotNull
java.util.List<TopLevelPlan> getAllPlans()
Returns all TopLevelPlan's

Returns:
plans

getAllPlansUnrestricted

java.util.List<TopLevelPlan> getAllPlansUnrestricted()
Returns all TopLevelPlan's ignoring permissions

Returns:

getAllPlans

@NotNull
<T extends Plan> java.util.List<T> getAllPlans(java.lang.Class<T> planType)
Returns all Plan's filtered by Class

Parameters:
planType - - the type of the plan to retrieve
Returns:
plans sorted by Plan.getName()

getAllPlansForClone

@NotNull
<T extends Plan> java.util.List<T> getAllPlansForClone(java.lang.Class<T> planType)
Returns all Plan's filtered by Class Return list filtered to show only plans the current user is allowed to clone.

Parameters:
planType - the class type of the plans you want returned
Returns:
plans

getPlansByProject

@NotNull
java.util.List<TopLevelPlan> getPlansByProject(Project project)
Returns all TopLevelPlan's filtered by Project

Parameters:
project - - that the plans will belong to
Returns:
TopLevelPlan plans contained within the given project

getPlansByProject

@NotNull
<T extends Plan> java.util.List<T> getPlansByProject(Project project,
                                                             java.lang.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> java.util.List<T> getAllPlansByProject(Project project,
                                                                java.lang.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> java.util.Map<Project,java.util.Collection<T>> getProjectPlanMap(java.lang.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

getPlanCount

int getPlanCount()
Returns:
How many Buildable's exists

getPlanCount

<T extends Plan> int getPlanCount(java.lang.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

savePlan

void savePlan(@NotNull
              Plan plan)
Saves the Plan

Parameters:
plan - to be saved

setPlanSuspendedState

void setPlanSuspendedState(Plan plan,
                           boolean newState)
Persists enable/disable state of a plan. Note that it will not persist the whole passed plan object, but only the value of isSuspendedFromBuilding field.

Parameters:
plan - to be suspended/resumed

updateLatestVcsKey

void updateLatestVcsKey(@NotNull
                        Plan plan,
                        @NotNull
                        java.lang.String vcsRevisionKey)
Updates the build to the latest passed revision key

Parameters:
plan - - Plan key
vcsRevisionKey - - revision key

updateVcsRevisionKey

java.lang.String updateVcsRevisionKey(@NotNull
                                      BuildContext buildContext)
Updates lastVcsRevisionKey in build based on revision contained in BuildContext

Parameters:
buildContext - containing the plan and vcs information to be persisted to the db.
Returns:
updated lastVcsRevisionKey

revertVcsRevisionKey

@Nullable
java.lang.String revertVcsRevisionKey(@NotNull
                                               java.lang.String buildKey,
                                               @NotNull
                                               java.lang.String revisionForBuild,
                                               @Nullable
                                               java.lang.String previousRevision)
Revert lastVcsRevisionKey in build based on previous build revision contained in BuildContext. The only reason to revert revision is for the situation, when build is abandoned and no subsequent build has been started. If subsequent build has been already started, there is no effect of reverting vcsRevisionKey

Parameters:
buildKey - - plan to revert
revisionForBuild - - the revision number that the build should be before reverting (used to see if another build may have started since this one.)
previousRevision - - the revision that the build should be reverted to if above conditions met
Returns:
the previousRevision

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;

updateNamesAndDescription

void updateNamesAndDescription(@NotNull
                               java.lang.String projectName,
                               @NotNull
                               java.lang.String buildName,
                               @Nullable
                               java.lang.String description,
                               @NotNull
                               Plan plan)
Updates project and plan names and plan description. All validation should have already occurred

Parameters:
projectName - new name of the project
buildName - new name of the plan
description - new plan description
plan - to update the details of

createPlan

void createPlan(Plan plan)
Same as savePlan, but create permissions used instead of edit permissions.


deletePlan

void deletePlan(Plan plan)
Removes the plan object from the database. Does not do any other clean up work at all Please use the PlanDeletionService rather than using this method directly

Parameters:
plan - to delete.

movePlanToProject

java.util.Map<PlanKey,PlanKey> movePlanToProject(Plan plan,
                                                 Project project,
                                                 java.lang.String newPlanKey,
                                                 java.lang.String newBuildName)
Moves plan to a selected project. Rewrites plan's and (if applicable) jobs' keys accordingly. Does not migrate ResultsSummaries or files.

Parameters:
plan - - plan to be moved/renamed
project - - project plan should be moved to
newPlanKey - - new key for the plan (not a full key)
newBuildName - - new name for the plan
Returns:
- mapping between original and updated plan keys

getFavouritePlans

java.util.Set<TopLevelPlan> getFavouritePlans(@NotNull
                                              com.atlassian.user.User user)

filterFavouritedPlans

@NotNull
java.util.Set<TopLevelPlan> filterFavouritedPlans(@NotNull
                                                          java.util.Collection<TopLevelPlan> plans,
                                                          @NotNull
                                                          com.atlassian.user.User user)
Return a set of Builds that are a subset of the given TopLevelPlans collection that are favourited by the User

Parameters:
plans - to filter
user - to return the favourites of
Returns:
a set of Builds that are a subset of the given TopLevelPlans collection that are favourited by the User

getAllPlansMarkedForDeletion

@NotNull
<T extends Plan> java.util.Collection<T> getAllPlansMarkedForDeletion(java.lang.Class<T> planType)
Returns a list of Plans that are com.atlassian.bamboo.plan.Plan#markForDeletion() for the given type

Returns:
plansMarkedForDeletion


Copyright © 2011 Atlassian. All Rights Reserved.