Package 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 Detail

      • getPlanIdentifierForPermissionCheckingByKey

        @Nullable
@Nullable PlanIdentifier getPlanIdentifierForPermissionCheckingByKey​(@NotNull
                                                                     @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
<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

      • getPlanByKey

        @Nullable
<T extends Plan> T getPlanByKey​(@NotNull
                                @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
                                        @NotNull PlanKey planKey,
                                        @NotNull
                                        @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
<T extends Plan> @NotNull 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> @NotNull 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> @NotNull 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
@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
@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> @NotNull 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> @NotNull 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> @NotNull 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> @NotNull List<PlanIdentifier> getPlanIdentifiersForProject​(@NotNull
                                                                            @NotNull ProjectIdentifier project,
                                                                            @NotNull
                                                                            @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
                                      @NotNull com.atlassian.user.User user)

      • getFavouritePlansIds

        @NotNull
@NotNull Set<Long> getFavouritePlansIds​(@NotNull
                                        @NotNull com.atlassian.user.User user)
        Return a collection of Favourite plan ids.
        Parameters:
        user -
        Returns:
        favouritePlansIds

      • filterFavouritedPlans

        @NotNull
@NotNull Set<ImmutableChain> filterFavouritedPlans​(@NotNull
                                                   @NotNull Collection<? extends ImmutableChain> plans,
                                                   @NotNull
                                                   @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

      • 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
                 @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
                               @NotNull String projectKey,
                               long planIdToIgnore,
                               @NotNull
                               @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
                             @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
                             @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

      • getPlanClass

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

      • assertPlanPermission

        boolean assertPlanPermission​(@NotNull
                             @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
              @NotNull Plan plan)
        Saves the Plan
        Parameters:
        plan - to be saved

      • savePlanWithSchedulesStopped

        void savePlanWithSchedulesStopped​(@NotNull
                                  @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
                                                 @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
                @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 -

      • removeStages

        void removeStages​(@NotNull
                  @NotNull PlanKey key,
                  @NotNull
                  @NotNull Collection<Long> stageIds)
        Remove the tages from the plan specified. key must be for a Chain
        Parameters:
        key -
        stageIds -

      • getPlanByKey

        @Nullable
@Deprecated
@Nullable Plan getPlanByKey​(@NotNull
                            @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
                                @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