jenkins.scm.api

Class SCMNavigator

java.lang.Object

hudson.model.AbstractDescribableImpl<SCMNavigator>

jenkins.scm.api.SCMNavigator

All Implemented Interfaces:

ExtensionPoint, Describable<SCMNavigator>

Direct Known Subclasses:

SingleSCMNavigator

public abstract class SCMNavigator
extends AbstractDescribableImpl<SCMNavigator>
implements ExtensionPoint

An API for discovering new and navigating already discovered SCMSources within an organization. An implementation does not need to cache existing discoveries, but some form of caching is strongly recommended where the backing provider of repositories has a rate limiter on API calls.

Since:

0.3-beta-1

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
static AlternativeUiTextProvider.Message<SCMNavigator>	PRONOUN Replaceable pronoun of that points to a SCMNavigator.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SCMNavigator() Constructor.

Method Summary

Modifier and Type	Method and Description
void	afterSave(SCMNavigatorOwner owner) Callback from the SCMNavigatorOwner after the SCMNavigatorOwner has been saved.
protected void	checkInterrupt() Checks the Thread.interrupted() and throws an InterruptedException if it was set.
protected TaskListener	defaultListener(TaskListener listener) Turns a possibly null TaskListener reference into a guaranteed non-null reference.
List<Action>	fetchActions(SCMNavigatorOwner owner, SCMNavigatorEvent event, TaskListener listener) Fetches any actions that should be persisted for objects related to the specified owner.
Set<? extends SCMSourceCategory>	getCategories() Returns the set of SCMSourceCategory that this SCMNavigator supports.
SCMNavigatorDescriptor	getDescriptor()
String	getId() Returns the ID of the thing being navigated.
String	getPronoun() Get the term used in the UI to represent this kind of SCMNavigator.
List<SCMTrait<? extends SCMTrait<?>>>	getTraits() Gets the traits for this navigator.
protected abstract String	id() Generates the ID of the thing being navigated from the configuration of this SCMNavigator.
protected boolean	isCategoryEnabled(SCMSourceCategory category) Sub-classes can override this method to filter the categories that are available from a specific source.
protected void	resetId() If implementations are using DataBoundSetter on fields that affect the id() calculation then those fields must call resetId() if they may have invalidated the cached getId().
protected List<Action>	retrieveActions(SCMNavigatorOwner owner, SCMNavigatorEvent event, TaskListener listener) SPI for fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener).
void	setTraits(List<SCMTrait<? extends SCMTrait<?>>> traits) Sets the traits for this navigator.
void	visitSource(String sourceName, SCMSourceObserver observer) Looks for the named SCM source in a configured place.
abstract void	visitSources(SCMSourceObserver observer) Looks for SCM sources in a configured place.
void	visitSources(SCMSourceObserver observer, SCMHeadEvent<?> event) Looks for SCM sources in a configured place (scoped against a specific event).
void	visitSources(SCMSourceObserver observer, SCMSourceEvent<?> event) Looks for SCM sources in a configured place (scoped against a specific event).

Methods inherited from class java.lang.Object

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

Field Detail

PRONOUN

public static final AlternativeUiTextProvider.Message<SCMNavigator> PRONOUN

Replaceable pronoun of that points to a SCMNavigator. Defaults to null depending on the context.

Since:

2.0

Constructor Detail

SCMNavigator

protected SCMNavigator()

Constructor.

Method Detail

getId

@NonNull
public final String getId()

Returns the ID of the thing being navigated.

The ID will typically be a composite of things like the server and the project/organization that the navigator is scoped to.

For example, a GitHub navigator that is navigating repositories in a GitHub organization could construct its ID as being the URL of the GitHub Server (to allow for GitHub Enterprise servers) and the name of the organization.

The key criteria is that if two navigators have the same ID and they are both in the same SCMNavigatorOwner then the results from fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener) should be not just equivalent but List.equals(Object).

Returns:

the ID of the thing being navigated by this navigator.

Since:

2.0.1

See Also:

id()

resetId

protected final void resetId()

If implementations are using DataBoundSetter on fields that affect the id() calculation then those fields must call resetId() if they may have invalidated the cached getId().

Since:

2.0.1

id

@NonNull
protected abstract String id()

Generates the ID of the thing being navigated from the configuration of this SCMNavigator.

The ID will typically be a composite of things like the server and the project/organization that the navigator is scoped to.

For example, a GitHub navigator that is navigating repositories in a GitHub organization could construct its ID as being the URL of the GitHub Server (to allow for GitHub Enterprise servers) and the name of the organization.

The key criteria is that if two navigators have the same ID and they are both in the same SCMNavigatorOwner then the results from fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener) should be not just equivalent but List.equals(Object).

If the results could be non-equal for navigators with the same ID then more detail needs to be encoded in the ID.

Returns:

the ID of the thing being navigated by this navigator.

Since:

2.0.1

See Also:

resetId(), getId()

setTraits

public void setTraits(@CheckForNull
                      List<SCMTrait<? extends SCMTrait<?>>> traits)

Sets the traits for this navigator. No-op by default.

Parameters:

traits - the list of traits

getTraits

@NonNull
public List<SCMTrait<? extends SCMTrait<?>>> getTraits()

Gets the traits for this navigator.

Returns:

traits the list of traits, empty by default.

visitSources

public abstract void visitSources(@NonNull
                                  SCMSourceObserver observer)
                           throws IOException,
                                  InterruptedException

Looks for SCM sources in a configured place. After this method completes, no further calls may be made to the observer or its child callbacks. It is vitally important that implementations must periodically call checkInterrupt() otherwise it will be impossible for users to interrupt the operation.

Parameters:

observer - a recipient of progress notifications and a source of contextual information

Throws:

IOException - if scanning fails

InterruptedException - if scanning is interrupted

visitSources

public void visitSources(@NonNull
                         SCMSourceObserver observer,
                         @NonNull
                         SCMSourceEvent<?> event)
                  throws IOException,
                         InterruptedException

Looks for SCM sources in a configured place (scoped against a specific event). After this method completes, no further calls may be made to the observer or its child callbacks. It is vitally important that implementations must periodically call checkInterrupt() otherwise it will be impossible for users to interrupt the operation.

Parameters:

observer - a recipient of progress notifications and a source of contextual information

event - the event from which the operation should be scoped.

Throws:

IOException - if scanning fails

InterruptedException - if scanning is interrupted

Since:

2.0

visitSources

public void visitSources(@NonNull
                         SCMSourceObserver observer,
                         @NonNull
                         SCMHeadEvent<?> event)
                  throws IOException,
                         InterruptedException

Looks for SCM sources in a configured place (scoped against a specific event). After this method completes, no further calls may be made to the observer or its child callbacks. It is vitally important that implementations must periodically call checkInterrupt() otherwise it will be impossible for users to interrupt the operation.

Parameters:

observer - a recipient of progress notifications and a source of contextual information

event - the event from which the operation should be scoped.

Throws:

IOException - if scanning fails

InterruptedException - if scanning is interrupted

Since:

2.0

visitSource

public void visitSource(@NonNull
                        String sourceName,
                        @NonNull
                        SCMSourceObserver observer)
                 throws IOException,
                        InterruptedException

Looks for the named SCM source in a configured place. Implementers must ensure that after this method completes, no further calls may be made to the observer or its child callbacks. Implementations are strongly encouraged to override this method.

Parameters:

sourceName - the source to visit.

observer - a recipient of progress notifications and a source of contextual information

Throws:

IOException - if scanning fails

InterruptedException - if scanning is interrupted

Since:

2.0

getCategories

@NonNull
public final Set<? extends SCMSourceCategory> getCategories()

Returns the set of SCMSourceCategory that this SCMNavigator supports. There will always be exactly one SCMCategory.isUncategorized() instance in the returned set.

Returns:

the set of SCMSourceCategory that this SCMNavigator supports.

Since:

2.0

isCategoryEnabled

protected boolean isCategoryEnabled(@NonNull
                                    SCMSourceCategory category)

Sub-classes can override this method to filter the categories that are available from a specific source. For example a source type might be capable of having mainline branches, user branches, merge requests and release tags while a specific instance of the source may be configured to only have mainline branches and release tags.

Parameters:

category - the category.

Returns:

true if the supplied category is enabled for this SCMNavigator instance.

Since:

2.0

getDescriptor

public SCMNavigatorDescriptor getDescriptor()

Specified by:

getDescriptor in interface Describable<SCMNavigator>

Overrides:

getDescriptor in class AbstractDescribableImpl<SCMNavigator>

getPronoun

@CheckForNull
public String getPronoun()

Get the term used in the UI to represent this kind of SCMNavigator. Must start with a capital letter.

Returns:

the term or null to fall back to the calling context's default.

Since:

2.0

fetchActions

@NonNull
public final List<Action> fetchActions(@NonNull
                                                SCMNavigatorOwner owner,
                                                @CheckForNull
                                                SCMNavigatorEvent event,
                                                @CheckForNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

Fetches any actions that should be persisted for objects related to the specified owner. For example, if a Item owns a specific SCMNavigator, then this method would be called to refresh any Action instances of that Item.

It is the responsibility of the caller to ensure that these Action instances are exposed on the Item for example by providing a TransientActionFactory implementation that reports these persisted actions separately (for example AbstractProject.getActions() returns an immutable list, so there is no way to persist the actions from this method against those sub-classes, instead the actions need to be persisted by some side mechanism and then injected into the Actionable.getAllActions() through a TransientActionFactory ignoring the cognitive dissonance triggered by adding non-transient actions through a transient action factory... think of it instead as a TemporalActionFactory that adds actions that can change over time)

Parameters:

owner - the owner of this SCMNavigator.

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

retrieveActions

@NonNull
protected List<Action> retrieveActions(@NonNull
                                                SCMNavigatorOwner owner,
                                                @CheckForNull
                                                SCMNavigatorEvent event,
                                                @NonNull
                                                TaskListener listener)
                                         throws IOException,
                                                InterruptedException

SPI for fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener). Fetches any actions that should be persisted for objects related to the specified owner.

Parameters:

owner - the owner of this SCMNavigator.

event - the (optional) event to use when fetching the actions. Where the implementation is able to trust the event, it may use the event payload to reduce the number of network calls required to obtain the actions.

listener - the listener to report progress on.

Returns:

the list of Action instances to persist.

Throws:

IOException - if an error occurs while performing the operation.

InterruptedException - if any thread has interrupted the current thread.

Since:

2.0

defaultListener

@NonNull
protected final TaskListener defaultListener(@CheckForNull
                                                      TaskListener listener)

Turns a possibly null TaskListener reference into a guaranteed non-null reference.

Parameters:

listener - a possibly null TaskListener reference.

Returns:

guaranteed non-null TaskListener.

checkInterrupt

protected final void checkInterrupt()
                             throws InterruptedException

Checks the Thread.interrupted() and throws an InterruptedException if it was set.

Throws:

InterruptedException - if interrupted.

Since:

2.0

afterSave

public void afterSave(@NonNull
                      SCMNavigatorOwner owner)

Callback from the SCMNavigatorOwner after the SCMNavigatorOwner has been saved. Can be used to register the SCMNavigatorOwner for a call-back hook from the backing SCM that this navigator is for. Implementations are responsible for ensuring that they do not create duplicate registrations and that orphaned registrations are removed eventually.

Parameters:

owner - the SCMNavigatorOwner.

Since:

2.0