Package jenkins.scm.api

Class SCMCategory<T>

  • Type Parameters:
    T - the type of thing.
    Direct Known Subclasses:
    SCMHeadCategory, SCMSourceCategory
    public abstract class SCMCategory<T>
extends Object
    Base class for categories of SCM things.
    A rose by any other name would smell as sweet?
    Naming things is hard. Naming things related to a source control system is even harder. It would be really nice if all the source control systems could agree on a standard set or terminologies for how to name things to do with source control systems. You are reading this and thinking "but how bad can it be?":
    • Git - Git uses the following terminology:
      • Each versioned tree of source files in Git is called a "Commit"
      • The collection of semi-related commits in Git is called a "Repository"
      • Each commit has a history of previous commits. Each Git repository has a collection of references to commits. Mutable references are called "Branches". Immutable references are called "Tags"
      • The remote place where all the Git repositories are kept is called a "Server"
      So we have "Commits"; "Branches" and "Tags"; "Repositories"; and "Servers"
    • AccuRev - AccuRev uses the following terminology:
      • Accurev tracks a tree of files, each file has a "Version"
      • Each tree of files starts from a single initiation point and that tree's multiple evolutions are all tracked in a single "Depot"
      • Each depot has a collection of references to version states of the tree at different points in time. Mutable references are called "Streams". Immutable references are called "Snapshots"
      • The remote place where all the Accurev depots are kept is called a "Repository"
      So we have "Versions"; "Streams" and "Snapshots"; "Depots"; and "Repositories"
    • Subversion - Subversion is really a versioned filesystem and people use conventions to do source control with the versioned file system. There are two common conventions:
      • Keep one project per repository
      • Keep multiple projects per repository, each with their own sub-tree
      The other common convention is the use of trunk / branches/___ / tags/___ structure for each project.

      So, if following conventions you might have "commits"; "trunk", "branches" and "tags"; "projects" or "repositories"; and "repositories" or "servers"

    So if a UI is calling something a collection of "Repositories" that may mean different things to different users depending on the source control system they are using. It would be really good if the SCM API enabled the implementations to provide their names and categories of names.

    For example:

    • A GitHub implementation of the SCM API might return "Branches", "Pull Requests", and "Tags" as the different types of SCMHead discovered by its SCMSource. It might return "Repositories" and "Forks" as the different types of project discovered by its SCMNavigator.
    This class is the base class for the different kinds of categorizations. Currently the SCM API supports two specializations:
    Since:
    2.0

    • Constructor Detail

      • SCMCategory

        public SCMCategory​(@CheckForNull
                   org.jvnet.localizer.Localizable displayName)
        Constructs an uncategorized category with the specified display name.
        Parameters:
        displayName - the display name.

      • SCMCategory

        public SCMCategory​(@NonNull
                   String name,
                   @CheckForNull
                   org.jvnet.localizer.Localizable displayName)
        Constructs a named category with the specified display name.
        Parameters:
        name - the name of the category. This will likely be used as a path component in building URLs
        displayName - the display name.
        Throws:
        IllegalArgumentException - if the supplied name is default

    • Method Detail

      • toDisplayName

        @NonNull
public static <C extends SCMCategory<?>> org.jvnet.localizer.Localizable toDisplayName​(C... categories)
        Gets the composite display name for a collection of SCMCategory instances.
        Type Parameters:
        C - the type of categories.
        Parameters:
        categories - the categories.
        Returns:
        the composite display name for the categories

      • toDisplayName

        @NonNull
public static <C extends SCMCategory<?>> org.jvnet.localizer.Localizable toDisplayName​(@NonNull
                                                                                       List<C> categories)
        Gets the composite display name for a collection of SCMCategory instances.
        Type Parameters:
        C - the type of categories.
        Parameters:
        categories - the categories.
        Returns:
        the composite display name for the categories

      • toShortUrl

        @NonNull
public static <C extends SCMCategory<?>> String toShortUrl​(C... categories)
        Gets the composite short url name for a collection of SCMCategory instances.
        Type Parameters:
        C - the type of categories.
        Parameters:
        categories - the categories.
        Returns:
        the composite short url name for the categories

      • toShortUrl

        @NonNull
public static <C extends SCMCategory<?>> String toShortUrl​(List<C> categories)
        Gets the composite short url name for a collection of SCMCategory instances.
        Type Parameters:
        C - the type of categories.
        Parameters:
        categories - the categories.
        Returns:
        the composite short url name for the categories

      • group

        @NonNull
public static <T,​C extends SCMCategory<T>> Map<String,​List<C>> group​(C... categories)
        Partitions a list of SCMCategory instances by getName().
        Type Parameters:
        T - the base type of thing.
        C - the base type of category.
        Parameters:
        categories - the categories to group.
        Returns:
        the map of sorted SCMCategory instances keyed by getName().

      • group

        @NonNull
public static <T,​C extends SCMCategory<T>> Map<String,​List<C>> group​(@NonNull
                                                                                 Iterable<C> categories)
        Partitions a collection of SCMCategory instances by getName().
        Type Parameters:
        T - the base type of thing.
        C - the base type of category.
        Parameters:
        categories - the categories to group.
        Returns:
        the map of sorted SCMCategory instances keyed by getName().

      • getName

        @NonNull
public final String getName()
        Gets the url path component to use when building URLs from categories.
        Returns:
        the url path component;

      • getDisplayName

        @NonNull
public org.jvnet.localizer.Localizable getDisplayName()
        Get the term used in the UI to represent a collection of things in this kind of SCMCategory. Must be a plural and start with a capital letter.
        Returns:
        the term for a collection of things in this kind of SCMCategory.

      • defaultDisplayName

        @NonNull
protected abstract org.jvnet.localizer.Localizable defaultDisplayName()
        The default display name.
        Returns:
        The generic term of a collection of things in this kind of SCMCategory.

      • isUncategorized

        public final boolean isUncategorized()
        Checks if this is the uncategorized category. The uncategorized category is special as isMatch(Object) will not be applied, rather the uncategorized category will pick up everything that has not been captured by another category.
        Returns:
        true if this is a catch-all category.

      • isMatch

        public abstract boolean isMatch​(@NonNull
                                T instance)
        Checks if the supplied instance is a match for this SCMCategory.
        Parameters:
        instance - the instance to test.
        Returns:
        true if the instance belongs to this SCMCategory.

      • isMatch

        public boolean isMatch​(@NonNull
                       T instance,
                       @Nullable
                       Iterable<? extends SCMCategory<T>> categories)
        Checks if the supplied instance is a match for this SCMCategory.
        Parameters:
        instance - the instance to test.
        categories - ignored unless isUncategorized() in which case it should be the list of categories.
        Returns:
        true if the instance belongs to this SCMCategory.