Package hudson.plugins.project_inheritance.projects.inheritance

Class ParameterSelector

java.lang.Object

hudson.plugins.project_inheritance.projects.inheritance.InheritanceSelector<JobProperty<?>>

hudson.plugins.project_inheritance.projects.inheritance.ParameterSelector

All Implemented Interfaces:

ExtensionPoint, Serializable

public class ParameterSelector
extends InheritanceSelector<JobProperty<?>>

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ParameterSelector.ScopeEntry

Nested classes/interfaces inherited from class hudson.plugins.project_inheritance.projects.inheritance.InheritanceSelector

InheritanceSelector.MODE

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
static ParameterSelector	instance
static String	VERSION_PARAM_NAME

Constructor Summary

Constructors

Constructor	Description
ParameterSelector()

Method Summary

Modifier and Type	Method	Description
List<ParameterSelector.ScopeEntry>	getAllScopedParameterDefinitions(InheritanceProject root)	Returns all parameter definitions that are involved in generating parameter values.
InheritanceSelector.MODE	getModeFor(Class<?> clazz)	This method decides which mode should be used for the given class, if your selector supports that type at all!
String	getObjectIdentifier(JobProperty<?> obj)	This method returns an identifier for the given object.
List<ParameterSelector.ScopeEntry>	getScopedParameterDefinition(InheritanceProject root, String name)
JobProperty<?>	handleSingleton(JobProperty<?> jp, InheritanceProject caller)	This method is triggered, when a singleton is encountered -- either after everything has been merged or there is only a single value left.
boolean	isApplicableFor(Class<?> clazz)	This method must return true, if the given Class is a valid supertype of the generic class used by your type.
JobProperty<?>	merge(JobProperty<?> prior, JobProperty<?> latter, InheritanceProject caller)	This function is called when InheritanceSelector.isApplicableFor(Class) returned the InheritanceSelector.MODE.MERGE mode and the two objects have the same ID as returned by InheritanceSelector.getObjectIdentifier(Object).

Methods inherited from class hudson.plugins.project_inheritance.projects.inheritance.InheritanceSelector

all, applyAgainstList

Methods inherited from class java.lang.Object

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

Field Detail

VERSION_PARAM_NAME

public static final String VERSION_PARAM_NAME

See Also:

Constant Field Values

instance

@Extension
public static final ParameterSelector instance

Constructor Detail

ParameterSelector

public ParameterSelector()

Method Detail

isApplicableFor

public boolean isApplicableFor(Class<?> clazz)

Description copied from class: InheritanceSelector

This method must return true, if the given Class is a valid supertype of the generic class used by your type.

For example, if your selector handles a specific JobProperty, this method must return true if you encounter a JobProperty.

This is used to do a fast pre-selection of which selectors to consider for the basic types offered by Jenkins (Properties, BuildSteps, Publishers, etc. pp.).

Expect to see lots of ClassCastExceptions or your code not even being called, if you violate this.

Specified by:

isApplicableFor in class InheritanceSelector<JobProperty<?>>

Parameters:

clazz - the type of objects to check

Returns:

true, if this selector applies to the given type of objects.

getModeFor

public InheritanceSelector.MODE getModeFor(Class<?> clazz)

Description copied from class: InheritanceSelector

This method decides which mode should be used for the given class, if your selector supports that type at all!

The latter part is essential, since returning anything other than InheritanceSelector.MODE.NOT_RESPONSIBLE for a type that your selector can't handle will result in ClassCastException or broken inheritance.

The default mode if no selector is matches is InheritanceSelector.MODE.USE_LAST, meaning that the last object overwrites and hides all the others defined earlier.

Specified by:

getModeFor in class InheritanceSelector<JobProperty<?>>

Parameters:

clazz - the class of elements under inspection

Returns:

how to handle lists containing these elements

getObjectIdentifier

public String getObjectIdentifier(JobProperty<?> obj)

Description copied from class: InheritanceSelector

This method returns an identifier for the given object. The identifier should be unique, as long as the objects are not the same in terms of inheritance. If they are the same their ID must also be the same.

One example is parameters. If you have two objects for the parameter with the name "foo", they should get the same ID, because they logically define the same element in terms of inheritance and thus should either be merged or override each other.

The purpose of this function is that candidates for merges can be identified by looping once through the list and then merging them in pairs or simply selection the last occurring one.

Specified by:

getObjectIdentifier in class InheritanceSelector<JobProperty<?>>

Parameters:

obj - the object that should be identified.

Returns:

an ID that is the same for multiple objects, if they define the same logical entity in terms of inheritance. Otherwise, the ID must be unique - or null, if this selector is not responsible for this object type.

merge

public JobProperty<?> merge(JobProperty<?> prior,
                            JobProperty<?> latter,
                            InheritanceProject caller)

Description copied from class: InheritanceSelector

This function is called when InheritanceSelector.isApplicableFor(Class) returned the InheritanceSelector.MODE.MERGE mode and the two objects have the same ID as returned by InheritanceSelector.getObjectIdentifier(Object).

It is expected of this function to merge the two objects together. This may or may not create a new object, but should not modify the two given objects.

Do note that this function is only called, if there are at least 2 elements to merge. If any post-processing or singleton-handling is necessary, use InheritanceSelector.handleSingleton(Object, InheritanceProject).

Specified by:

merge in class InheritanceSelector<JobProperty<?>>

Parameters:

prior - the earlier defined object

latter - the later defined object

caller - the job for which the merge is done

Returns:

a merged instance. Maybe be new, or one of the input elements

handleSingleton

public JobProperty<?> handleSingleton(JobProperty<?> jp,
                                      InheritanceProject caller)

This method is triggered, when a singleton is encountered -- either after everything has been merged or there is only a single value left.

Specified by:

handleSingleton in class InheritanceSelector<JobProperty<?>>

Parameters:

jp - the object selected to be returned to Jenkins.

caller - the project for which the inheritance is determined.

Returns:

the object that should actually be returned to Jenkins. Do note that it may be part of a list, in which case the returned value replaces the original value.

getAllScopedParameterDefinitions

public List<ParameterSelector.ScopeEntry> getAllScopedParameterDefinitions(InheritanceProject root)

Returns all parameter definitions that are involved in generating parameter values.

It walks the inheritance tree for the current request and generates a list of all parameter declarations that are involved in generating the final values of all parameters.

The returned list is sorted in order of when each definition is encountered, so it walks from the current project upwards. Do note that it is likely, that parameters with the same name are not stored sequentially.

Beware: The returned scope contains the original ParameterDefinitions, as they are stored in the project class instances. Each individual parameter has no idea about its position in the inheritance. If you need finalized values, you need to use InheritableStringParameterDefinition.getMergeWithOther(ParameterDefinition) or createMerged(ParametersDefinitionProperty, ParametersDefinitionProperty)

Parameters:

root - the project for which to retrieve the parameter scope

Returns:

a list of ParameterSelector.ScopeEntry instances, sorted by order of derivation by inheritance. Never null, but may be empty.

getScopedParameterDefinition

public List<ParameterSelector.ScopeEntry> getScopedParameterDefinition(InheritanceProject root,
                                                                       String name)