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:

• SCMHeadCategory is used to categorize SCMHead instances returned by a SCMSource
• SCMSourceCategory is used to categorize SCMSource instances returned by a SCMNavigator

Since:

2.0

Constructor Summary

Constructors

Constructor and Description
SCMCategory(org.jvnet.localizer.Localizable displayName) Constructs an uncategorized category with the specified display name.
SCMCategory(String name, org.jvnet.localizer.Localizable displayName) Constructs a named category with the specified display name.

Method Summary

Modifier and Type	Method and Description
protected abstract org.jvnet.localizer.Localizable	defaultDisplayName() The default display name.
org.jvnet.localizer.Localizable	getDisplayName() Get the term used in the UI to represent a collection of things in this kind of SCMCategory.
String	getName() Gets the url path component to use when building URLs from categories.
static <T,C extends SCMCategory<T>> Map<String,List<C>>	group(C... categories) Partitions a list of SCMCategory instances by getName().
static <T,C extends SCMCategory<T>> Map<String,List<C>>	group(Iterable<C> categories) Partitions a collection of SCMCategory instances by getName().
abstract boolean	isMatch(T instance) Checks if the supplied instance is a match for this SCMCategory.
boolean	isMatch(T instance, Iterable<? extends SCMCategory<T>> categories) Checks if the supplied instance is a match for this SCMCategory.
boolean	isUncategorized() Checks if this is the uncategorized category.
static <C extends SCMCategory<?>> org.jvnet.localizer.Localizable	toDisplayName(C... categories) Gets the composite display name for a collection of SCMCategory instances.
static <C extends SCMCategory<?>> org.jvnet.localizer.Localizable	toDisplayName(List<C> categories) Gets the composite display name for a collection of SCMCategory instances.
static <C extends SCMCategory<?>> String	toShortUrl(C... categories) Gets the composite short url name for a collection of SCMCategory instances.
static <C extends SCMCategory<?>> String	toShortUrl(List<C> categories) Gets the composite short url name for a collection of SCMCategory instances.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.