Package jenkins.scm.api

Class SCMCategory<T>

java.lang.Object
jenkins.scm.api.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 Details

    • 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 Details

    • 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.