Package hudson.plugins.project_inheritance.projects.inheritance

Class InheritanceGovernor<T>

java.lang.Object

hudson.plugins.project_inheritance.projects.inheritance.InheritanceGovernor<T>

Type Parameters:

T - the target type of the field this helper is written for.

public abstract class InheritanceGovernor<T>
extends Object

This class offers a few helper functions to facilitate correct inheritance and versioning of the various types of fields of Jenkins projects.

Author:

Martin Schroeder

Field Summary

Fields

Modifier and Type	Field	Description
InheritanceProject	caller
String	fieldName
ProjectReference.PrioComparator.SELECTOR	orderMode
static Pattern	runUriRegExp

Constructor Summary

Constructors

Constructor	Description
InheritanceGovernor(String field, ProjectReference.PrioComparator.SELECTOR order, InheritanceProject caller)

Method Summary

Modifier and Type	Method	Description
protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>>	castToDescribableList(Object o)
protected abstract T	castToDestinationType(Object o)	This function should take an arbitrary Object o and cast it directly to T if possible; or return null if o is incompatible.
protected static <R> List<R>	castToList(Object o)
static List<InheritanceProject>	getFullScopeOrdered(InheritanceProject root, ProjectReference.PrioComparator.SELECTOR order, Set<String> seen)	Returns the list of parents of a given job (including the given root), ordered according to the given selector.
abstract T	getRawField(InheritanceProject ip)
T	getVersionedField(InheritanceProject ip, Long version)
static boolean	inheritanceLookupRequired(InheritanceProject root)
static boolean	inheritanceLookupRequired(InheritanceProject root, boolean forcedInherit)
protected static <R> List<R>	reduceByMerge(Deque<List<R>> list, Class<?> listType, InheritanceProject caller)	Simple helper function to use a merge as the default reduction.
protected static <R> List<R>	reduceByMergeWithDuplicates(Deque<List<R>> list, Class<?> listType, InheritanceProject caller)	Simple helper function to use a merge as the default reduction.
protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>>	reduceDescribableByMerge(Deque<DescribableList<R,Descriptor<R>>> list)
protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>>	reduceDescribableByMergeWithoutDuplicates(Deque<DescribableList<R,Descriptor<R>>> list)
protected T	reduceFromFullInheritance(Deque<T> list)	This is a reduction function that is tasked to reduce the List<T> that is generated through inheritance down to a single T.
T	retrieveFullyDerivedField(InheritanceProject root, InheritanceProject.IMode mode)	This method moves through as much of the inheritance tree as is necessary to retrieve the desired field as defined by this class.
protected static boolean	versioningRequired()	This method uses reflection to tell whether the current state means that versioning is needed or not.

Methods inherited from class java.lang.Object

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

Field Detail

runUriRegExp

public static final Pattern runUriRegExp

fieldName

public final String fieldName

orderMode

public final ProjectReference.PrioComparator.SELECTOR orderMode

caller

public final InheritanceProject caller

Constructor Detail

InheritanceGovernor

public InheritanceGovernor(String field,
                           ProjectReference.PrioComparator.SELECTOR order,
                           InheritanceProject caller)

Method Detail

castToDestinationType

protected abstract T castToDestinationType(Object o)

This function should take an arbitrary Object o and cast it directly to T if possible; or return null if o is incompatible.

It must not return a copy. It must cast directly or return null. This property will be checked by this class and a nasty exception will be thrown by this class if you violate it.

Parameters:

o - the object to be cast directly without copying.

Returns:

o recast as the type T, if possible.

getRawField

public abstract T getRawField(InheritanceProject ip)

getVersionedField

public T getVersionedField(InheritanceProject ip,
                           Long version)

retrieveFullyDerivedField

public final T retrieveFullyDerivedField(InheritanceProject root,
                                         InheritanceProject.IMode mode)

This method moves through as much of the inheritance tree as is necessary to retrieve the desired field as defined by this class.

Parameters:

root - the project from which to start derivation.

mode - the mode of inheritance to use.

Returns:

the final element. Will be a copy if multiple inherited values are combined or a specific version is requested. Will only be the actual field reference if in "AUTO" mode and under very specific circumstances where this plugin is SURE that the actual field is needed.

getFullScopeOrdered

public static final List<InheritanceProject> getFullScopeOrdered(InheritanceProject root,
                                                                 ProjectReference.PrioComparator.SELECTOR order,
                                                                 Set<String> seen)

Returns the list of parents of a given job (including the given root), ordered according to the given selector.

Parameters:

root - the job to get parents for.

order - the order to use.

seen - a set of names of projects which have already been included. If null, an empty set is used.

Returns:

the list of parents, including the given root. As such, is never empty or null.

reduceFromFullInheritance

protected T reduceFromFullInheritance(Deque<T> list)

This is a reduction function that is tasked to reduce the List<T> that is generated through inheritance down to a single T.

This might mean merging the elements of the list or just selecting one entry. The default implementation simply selects the last non-null element. If none are present; it returns null.

Do note that there's also the InheritanceSelector extension point which should be applied for certain fields of a Job class.

For example, the "properties" element has a list as the type T here. This means, the reduction helper will first merge the list and then try to apply one of the InheritanceSelector classes. The same is true for build-wrappers, build steps, publishers and more.

Some implementations may also skip the first part since they are tasked not to return a List but a singleton value. As such, their reduction helper will apply the InheritanceSelector classes FIRST before stripping down the list to the single element they are tasked to build. An example would be the SCM property of a project.

Do note: This function is only applied if inheritance actually happened. It will neither be called when the local properties of a project are queried, nor if the project does not have any parents. Do note that the list may be empty or contain only a single element.

Parameters:

list - the list of fields from all the parents, sorted by their selected inheritance order.

Returns:

a single element T. Can be an element from the list or a merge of the list or even a newly generated element. The default implementation will simply return the last entry from the input list.

reduceByMergeWithDuplicates

protected static <R> List<R> reduceByMergeWithDuplicates(Deque<List<R>> list,
                                                         Class<?> listType,
                                                         InheritanceProject caller)

Simple helper function to use a merge as the default reduction.

Do note that the list is returned in-order of inheritance, with merges being put back into the list at the location of the last definition.

It will not de-duplicated the resulting list beyond doing the merges based on the InheritanceSelector extensions.

Type Parameters:

R - the type of the values in the given list.

Parameters:

list - the raw list to scan

listType - the type of elements in the list

caller - the project for which the merge is done

Returns:

a list of items resulting from the merge

See Also:

reduceFromFullInheritance(Deque), reduceByMerge(Deque, Class, InheritanceProject)

reduceByMerge

protected static <R> List<R> reduceByMerge(Deque<List<R>> list,
                                           Class<?> listType,
                                           InheritanceProject caller)

Simple helper function to use a merge as the default reduction.

Do note that the list is returned in-order of inheritance, with merges being put back into the list at the location of the last definition.

In contrast to reduceByMergeWithDuplicates(Deque, Class, InheritanceProject), it will remove duplicate entries based on the class-objects.

Type Parameters:

R - the type of the values in the given list.

Parameters:

list - the list to reduce

listType - the type of the list elements

caller - the project for which the list is being generated

Returns:

a reduced list. May be empty but never null.

See Also:

reduceFromFullInheritance(Deque)

reduceDescribableByMerge

protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>> reduceDescribableByMerge(Deque<DescribableList<R,Descriptor<R>>> list)

reduceDescribableByMergeWithoutDuplicates

protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>> reduceDescribableByMergeWithoutDuplicates(Deque<DescribableList<R,Descriptor<R>>> list)

castToList

protected static <R> List<R> castToList(Object o)

castToDescribableList

protected static <R extends Describable<R>> DescribableList<R,Descriptor<R>> castToDescribableList(Object o)

inheritanceLookupRequired

public static boolean inheritanceLookupRequired(InheritanceProject root)

inheritanceLookupRequired

public static boolean inheritanceLookupRequired(InheritanceProject root,
                                                boolean forcedInherit)

versioningRequired

protected static boolean versioningRequired()

This method uses reflection to tell whether the current state means that versioning is needed or not.

There is only one circumstance in which versioning should NOT be needed, and that is when Jenkins expects to access the original, raw fields of this class to directly manipulate them during reconfiguration.

Do note that both inheritanceLookupRequired(InheritanceProject) and this function need to return false for the raw lists to be returned by getVersionedField(InheritanceProject, Long).

Returns:

true if versioning for the various fields is needed.