Package jenkins.model.lazy

Class AbstractLazyLoadRunMap<R>

  • All Implemented Interfaces:
    Map<Integer,​R>, SortedMap<Integer,​R>
    Direct Known Subclasses:
    RunMap
    public abstract class AbstractLazyLoadRunMap<R>
extends AbstractMap<Integer,​R>
implements SortedMap<Integer,​R>
    SortedMap that keeps build records by their build numbers, in the descending order (newer ones first.)

    The main thing about this class is that it encapsulates the lazy loading logic. That is, while this class looks and feels like a normal SortedMap from outside, it actually doesn't have every item in the map instantiated yet. As items in the map get requested, this class retrieves them on demand, one by one.

    The lookup is done by using the build number as the key (hence the key type is Integer).

    This class makes the following assumption about the on-disk layout of the data:

    • Every build is stored in a directory, named after its number.

    Some of the SortedMap operations are weakly implemented. For example, AbstractMap.size() may be inaccurate because we only count the number of directories that look like build records, without checking if they are loadable. But these weaknesses aren't distinguishable from concurrent modifications, where another thread deletes a build while one thread iterates them.

    Some of the SortedMap operations are inefficiently implemented, by loading all the build records eagerly. We hope to replace these implementations by more efficient lazy-loading ones as we go.

    Object lock of this is used to make sure mutation occurs sequentially. That is, ensure that only one thread is actually calling retrieve(File) and updating AbstractLazyLoadRunMap.Index.byNumber.

    Since:
    1.485
    Author:
    Kohsuke Kawaguchi

    • Field Detail

      • dir

        protected File dir
        Base directory for data. In effect this is treated as a final field, but can't mark it final because the compatibility requires that we make it settable in the first call after the constructor.

    • Constructor Detail

      • AbstractLazyLoadRunMap

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
protected AbstractLazyLoadRunMap()

    • Method Detail

      • initBaseDir

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
protected void initBaseDir​(File dir)

      • updateBaseDir

        public final void updateBaseDir​(File dir)
        Updates base directory location after directory changes. This method should be used on jobs renaming, etc.
        Parameters:
        dir - Directory location
        Since:
        1.546

      • purgeCache

        public void purgeCache()
        Let go of all the loaded references. This is a bit more sophisticated version of forcing GC. Primarily for debugging and testing lazy loading behaviour.
        Since:
        1.507

      • allowLoad

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
protected boolean allowLoad​(int buildNumber)

      • recognizeNumber

        @Restricted(org.kohsuke.accmod.restrictions.Beta.class)
public final void recognizeNumber​(int buildNumber)
        Permits a previous blocked build number to be eligible for loading.
        Parameters:
        buildNumber - a build number
        See Also:
        RunListener.allowLoad(hudson.model.Job<?, ?>, int)

      • getLoadedBuilds

        public SortedMap<Integer,​R> getLoadedBuilds()
        Returns a read-only view of records that has already been loaded.

      • subMap

        public SortedMap<Integer,​R> subMap​(Integer fromKey,
                                         Integer toKey)
        Specified by:
        subMap in interface SortedMap<Integer,​R>
        Parameters:
        fromKey - Biggest build number to be in the returned set.
        toKey - Smallest build number-1 to be in the returned set (-1 because this is exclusive)

      • newestBuild

        public R newestBuild()

      • oldestBuild

        public R oldestBuild()

      • get

        public R get​(int n)

      • runExists

        public boolean runExists​(int number)
        Checks if the specified build exists.
        Parameters:
        number - the build number to probe.
        Returns:
        true if there is an run for the corresponding number, note that this does not mean that the corresponding record will load.
        Since:
        2.14

      • search

        @CheckForNull
public R search​(int n,
                AbstractLazyLoadRunMap.Direction d)
        Finds the build #M where M is nearby the given 'n'.
        Parameters:
        n - the index to start the search from
        d - defines what we mean by "nearby" above. If EXACT, find #N or return null. If ASC, finds the closest #M that satisfies M ≥ N. If DESC, finds the closest #M that satisfies M ≤ N.

      • getById

        public R getById​(String id)

      • getByNumber

        public R getByNumber​(int n)

      • maxNumberOnDisk

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public int maxNumberOnDisk()
        Returns:
        the highest recorded build number, or 0 if there are none

      • put

        public R put​(R value)

      • _put

        protected R _put​(R value)

      • getNumberOf

        protected abstract int getNumberOf​(R r)
        Subtype to provide Run.getNumber() so that this class doesn't have to depend on it.

      • getIdOf

        protected String getIdOf​(R r)
        Subtype to provide Run.getId() so that this class doesn't have to depend on it.

      • createReference

        protected BuildReference<R> createReference​(R r)
        Allow subtype to capture a reference.

      • retrieve

        protected abstract R retrieve​(File dir)
                       throws IOException
        Parses R instance from data in the specified directory.
        Returns:
        null if the parsing failed.
        Throws:
        IOException - if the parsing failed. This is just like returning null except the caller will catch the exception and report it.

      • removeValue

        public boolean removeValue​(R run)

      • reset

        public void reset​(TreeMap<Integer,​R> builds)
        Replaces all the current loaded Rs with the given ones.