Package com.atlassian.bamboo.plan.cache

Interface ImmutablePlanCacheService

  • All Known Implementing Classes:
    ImmutablePlanCacheServiceImpl
    @Internal
public interface ImmutablePlanCacheService
    An experimental API for getting immutable, weakly held, cached ImmutableChain. This Service does not check for permissions currently. Only works for Chain. Cache is disabled by default and should be explicitly enabled by application (preferably by calling initialiseCache())
    Concepts:
    cache invalidation
    Temporary removal of plan from cache (ie as an effect of changed plan configuration). Cache invalidation will remove Plan from cache but will not remove metadata information (ie planKey->id mapping)
    cache reset
    Permament removal of plan from cache (ie as an effect of plan deletion or move to another project). Cache reset will remove Plan and all related data from the cache.
    This class is for internal use only, you should probably be using CachedPlanManager instead. If the method does not contain `...WithConsistencyGuarantee` in its name, then it does not guarantee that the data is up-to-date a.k.a. highly consistent in the cluster mode.
    Since:
    v3.4

    • Method Detail

      • getImmutablePlanByKey

        @Nullable
@Nullable ImmutableChain getImmutablePlanByKey​(@NotNull
                                               @NotNull PlanKey planKey)
        Returns a plan if one exists with the key. Returns null if the plan doesn't exist or if the cache entry is currently inaccessible because it is locked by another caller. In clustered mode, there is NO consistency guarantee.
        See Also:
        withHiddenPlans(Collection, Supplier)

      • getImmutablePlanByKeyWithConsistencyGuarantee

        @Nullable
@Nullable ImmutableChain getImmutablePlanByKeyWithConsistencyGuarantee​(@NotNull
                                                                       @NotNull PlanKey planKey)
        Returns a plan if one exists with the key. Returns null if the plan doesn't exist or if the cache entry is currently inaccessible because it is locked by another caller. There is a guarantee that the data will be up-to-date.
        Since:
        9.4

      • getImmutablePlansByKeysWithConsistencyGuarantee

        @NotNull
@NotNull Stream<ImmutableChain> getImmutablePlansByKeysWithConsistencyGuarantee​(@NotNull
                                                                                @NotNull Collection<PlanKey> planKeys,
                                                                                boolean onlyLoaded)
        Returns a stream of found plans for requestes plan keys. There are no nulls in the stream. There is a guarantee that the data will be up-to-date.
        Since:
        9.4

      • getImmutablePlansByKeysWithConsistencyGuarantee

        @NotNull
@NotNull Stream<ImmutableChain> getImmutablePlansByKeysWithConsistencyGuarantee​(@NotNull
                                                                                @NotNull Collection<PlanKey> planKeys,
                                                                                boolean onlyLoaded,
                                                                                @NotNull
                                                                                @NotNull Collection<PlanKey> whiteListedPlans)
        Returns a stream of found plans for requested plan keys. There are no nulls in the stream. There is a guarantee that the data will be up-to-date. If BambooClusterSettings.isOptimisticLockingEnabled() is disabled, then no consistency is made.
        Parameters:
        planKeys - the plan keys to retrieve data for
        onlyLoaded - determines if keys not found in the cache will be loaded (false) or not (true)
        whiteListedPlans - the plans that are already considered up-to-date, i.e., they are already highly-consistent and no check will be made if they are found in the cache.
        Returns:
        the plans found in the cache and, if onlyLoaded=false, the eventual ones that were loaded.
        Since:
        9.4

      • getPlans

        @NotNull
<T extends ImmutablePlan> @NotNull Stream<T> getPlans​(Class<T> planType,
                                                      @NotNull
                                                      @NotNull com.google.common.base.Predicate<? super T> filter)
        Returns all Plan's filtered by Class. Does not include plans marked for deletion. In clustered mode, there is NO consistency guarantee.
        Parameters:
        planType - - the type of the plan to retrieve
        Returns:
        plans sorted by DescriptionProvider.getName()

      • getPlansWithConsistencyGuarantee

        @NotNull
<T extends ImmutablePlan> @NotNull Stream<T> getPlansWithConsistencyGuarantee​(Class<T> planType,
                                                                              @NotNull
                                                                              @NotNull com.google.common.base.Predicate<? super T> filter)
        Returns all Plan's filtered by Class. Does not include plans marked for deletion. There is a guarantee that the data will be up-to-date.
        Parameters:
        planType - - the type of the plan to retrieve
        Returns:
        plans sorted by DescriptionProvider.getName()
        Since:
        9.4

      • getBranchKeysOfChain

        @NotNull
@NotNull Stream<PlanKey> getBranchKeysOfChain​(@NotNull
                                              @NotNull PlanKey chainKey)
        Returns all cached branches associated with a master plan identified by the given key. For a highly-consistent implementation (with checks for eventual new branches in the database), please consider getBranchKeysOfChainWithConsistencyGuarantee(PlanKey).
        Parameters:
        chainKey - the key of the chain
        Returns:
        the branches present in the cache that are associated with a master plan identified by the given key
        Since:
        9.5

      • getBranchKeysOfChainWithConsistencyGuarantee

        @NotNull
@NotNull ImmutableCacheResults<PlanKey> getBranchKeysOfChainWithConsistencyGuarantee​(@NotNull
                                                                                     @NotNull PlanKey chainKey)
        Returns all branches associated with a master plan identified by a given plan key, with guarantee that eventual new plan branches not present in the cache will be taken in consideration.
        Parameters:
        chainKey - the key of the chain
        Returns:
        highly-consistent list of branches associated with a master plan identified by the given key, including cached and not-cached data.
        Since:
        9.5

      • getBranchGistsOfChain

        @NotNull
@NotNull Stream<PlanBranchGist> getBranchGistsOfChain​(@NotNull
                                                      @NotNull PlanKey chainKey)
        Returns the Gists of all cached branches associated with a master plan identified by the given key. For a highly-consistent implementation (with checks for eventual new branches in the database), please consider getBranchGistsOfChainWithConsistencyGuarantee(PlanKey).
        Parameters:
        chainKey - the key of the chain
        Returns:
        the branches' gists present in the cache that are associated with a master plan identified by the given key
        Since:
        9.5

      • getBranchGistsOfChainWithConsistencyGuarantee

        @NotNull
@NotNull ImmutableCacheResults<PlanBranchGist> getBranchGistsOfChainWithConsistencyGuarantee​(@NotNull
                                                                                             @NotNull PlanKey chainKey)
        Returns the Gists of all branches associated with a master plan identified by a given plan key, with guarantee that eventual new plan branches not present in the cache will be taken in consideration.
        Parameters:
        chainKey - the key of the chain
        Returns:
        highly-consistent list of branches' gists associated with a master plan identified by the given key, including cached and not-cached data.
        Since:
        9.5

      • getPlanKeysByProject

        @NotNull
<T extends ImmutablePlan> @NotNull Stream<PlanKey> getPlanKeysByProject​(long projectId,
                                                                        @NotNull
                                                                        @NotNull Class<T> planType)
        Returns all keys of all plans that belong to a project and have specified type.
        Since:
        9.3

      • withHiddenPlans

        <V> V withHiddenPlans​(Collection<PlanKey> planKeys,
                      Supplier<V> supplier)
        Invokes supplier while marking the specified plan keys as unavailable. Other callers will not be able to access the cache entries for the specified plans while the supplier is executing. The write locks will be obtained in a deterministic order to avoid deadlocks.
        Returns:
        the value produced by supplier.

      • getImmutableChainByKeyIfInCache

        @Nullable
@Nullable ImmutableChain getImmutableChainByKeyIfInCache​(@NotNull
                                                         @NotNull PlanKey planKey)

      • getImmutableChainByKeyIfInCacheWithConsistencyGuarantee

        @Nullable
@Nullable ImmutableChain getImmutableChainByKeyIfInCacheWithConsistencyGuarantee​(@NotNull
                                                                                 @NotNull PlanKey planKey)

      • invalidate

        void invalidate​(@NotNull
                @NotNull PlanKey planKey)
        Removes the cached Plan. Retains Plan metadata.
        Parameters:
        planKey - key of the Plan to be removed from cache

      • cascadeInvalidate

        void cascadeInvalidate​(@NotNull
                       @NotNull PlanKey planKey)
        Removes the cached reference for the passed plan and its children. Currently only propagates invalidation from Chain to ChainBranch
        Parameters:
        planKey - key of the Plan to be removed from cache

      • remove

        void remove​(@NotNull
            @NotNull PlanKey planKey)
        Removes the cached Plan and its metadata.
        Parameters:
        planKey - key of the Plan to be removed from cache

      • initialiseCache

        void initialiseCache()
        Clear the cache and attempt to read all Chains from DB in order to cache them. If cache was disabled it will be enabled by this method.

      • disableCache

        void disableCache()
        Disable cache. When cache is disabled all cache requests will be logged with severity WARN until cache will be enabled again. This method will clear cache.

      • enableCache

        void enableCache()
        Enable cache. This method will not load anything when it is enabled, you should consider calling initialiseCache() instead if you expect plans to be loaded.

      • isCacheEnabled

        boolean isCacheEnabled()
        Returns:
        true if cache is enabled
        Since:
        8.0

      • getCacheStats

        BambooCacheStats getCacheStats()
        Retrieve cache statistics
        Returns:
        Cache statistics

      • getIndices

        @NotNull
@NotNull PlanCacheIndices getIndices()
        Returns the indices created for plan cache content.

      • getBuildNumbersRange

        @Deprecated
@Internal
@NotNull
@NotNull Range<Integer> getBuildNumbersRange​(PlanKey planKey)
        Deprecated.
        since 5.10
        internal use only.

      • invalidateBuildNumbersRange

        @Deprecated
@Internal
void invalidateBuildNumbersRange​(PlanKey planKey,
                                 int buildNumber,
                                 boolean trueForSaveFalseForDelete)
        Deprecated.
        since 5.10
        internal use only.

      • invalidateLatestResultSummary

        void invalidateLatestResultSummary​(PlanResultKey key,
                                   boolean resetAverageBuildDuration)
        Resets the latest build summary of a plan. No op if we already cache a later plan result or we don't have plan or result cached.

      • invalidateAllLatestResultSummaries

        void invalidateAllLatestResultSummaries()
        Invalidates all latest result summaries currently cached.

      • invalidateSpecsStateForPlan

        void invalidateSpecsStateForPlan​(@NotNull
                                 @NotNull PlanKey planKey,
                                 @Nullable
                                 @Nullable ImmutableVcsBambooSpecsSource immutableVcsBambooSpecsSource)
        Invalidate specs state.
        Parameters:
        planKey - plan key
        immutableVcsBambooSpecsSource - new state

      • invalidateSpecsStateForPlan

        void invalidateSpecsStateForPlan​(@NotNull
                                 @NotNull PlanKey planKey)
        Invalidate specs state for a given planKey.
        Parameters:
        planKey - plan key
        Since:
        9.4.0

      • indexPlan

        @Internal
void indexPlan​(@NotNull
               @NotNull ImmutableChain plan)
        Updates plan indexes in cache

      • hideDeletedPlan

        void hideDeletedPlan​(PlanKey planKey)
        Hides the plan. Only the deletion thread will see it.

      • hideDeletedStage

        void hideDeletedStage​(Long stageId)
        Hides the stage. Only the deletion thread will see it.

      • isPlanBeingDeleted

        boolean isPlanBeingDeleted​(PlanKey planKey)

      • enterDeletionCodeSection

        void enterDeletionCodeSection()
        Marks the current thread as being able to see deleted plans.

      • leaveDeletionCodeSection

        void leaveDeletionCodeSection()
        Marks the current thread as no longer being able to see deleted plans.

      • filterOutDeletedIfNeeded

        @NotNull
<T extends ImmutableJob> @NotNull Set<T> filterOutDeletedIfNeeded​(@NotNull
                                                                  @NotNull Set<T> jobs)
        Returns a set with deleted jobs removed. When running under deletion code, returns the same set.

      • filterOutDeletedIfNeeded

        @NotNull
<T extends ImmutableChainStage> @NotNull List<T> filterOutDeletedIfNeeded​(@NotNull
                                                                          @NotNull List<T> stages)
        Returns a list with deleted stages removed. When running under deletion code, returns the same list.

      • onStageDeleted

        void onStageDeleted​(long stageId)