public abstract class SCMNavigator extends AbstractDescribableImpl<SCMNavigator> implements ExtensionPoint
SCMSource
s 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.ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
static AlternativeUiTextProvider.Message<SCMNavigator> |
PRONOUN
Replaceable pronoun of that points to a
SCMNavigator . |
Modifier | Constructor and Description |
---|---|
protected |
SCMNavigator()
Constructor.
|
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()
|
protected List<Action> |
retrieveActions(SCMNavigatorOwner owner,
SCMNavigatorEvent event,
TaskListener listener)
|
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).
|
public static final AlternativeUiTextProvider.Message<SCMNavigator> PRONOUN
SCMNavigator
. Defaults to null
depending on the context.@NonNull public final String getId()
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)
.
id()
protected final void resetId()
DataBoundSetter
on fields that affect the id()
calculation then
those fields must call resetId()
if they may have invalidated the cached getId()
.@NonNull protected abstract String id()
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.
public void setTraits(@CheckForNull List<SCMTrait<? extends SCMTrait<?>>> traits)
traits
- the list of traits@NonNull public List<SCMTrait<? extends SCMTrait<?>>> getTraits()
public abstract void visitSources(@NonNull SCMSourceObserver observer) throws IOException, InterruptedException
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.observer
- a recipient of progress notifications and a source of contextual informationIOException
- if scanning failsInterruptedException
- if scanning is interruptedpublic void visitSources(@NonNull SCMSourceObserver observer, @NonNull SCMSourceEvent<?> event) throws IOException, InterruptedException
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.observer
- a recipient of progress notifications and a source of contextual informationevent
- the event from which the operation should be scoped.IOException
- if scanning failsInterruptedException
- if scanning is interruptedpublic void visitSources(@NonNull SCMSourceObserver observer, @NonNull SCMHeadEvent<?> event) throws IOException, InterruptedException
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.observer
- a recipient of progress notifications and a source of contextual informationevent
- the event from which the operation should be scoped.IOException
- if scanning failsInterruptedException
- if scanning is interruptedpublic void visitSource(@NonNull String sourceName, @NonNull SCMSourceObserver observer) throws IOException, InterruptedException
observer
or its child callbacks. Implementations are strongly encouraged to override this method.sourceName
- the source to visit.observer
- a recipient of progress notifications and a source of contextual informationIOException
- if scanning failsInterruptedException
- if scanning is interrupted@NonNull public final Set<? extends SCMSourceCategory> getCategories()
SCMSourceCategory
that this SCMNavigator
supports. There will always be
exactly one SCMCategory.isUncategorized()
instance in the returned set.SCMSourceCategory
that this SCMNavigator
supports.protected boolean isCategoryEnabled(@NonNull SCMSourceCategory category)
category
- the category.true
if the supplied category is enabled for this SCMNavigator
instance.public SCMNavigatorDescriptor getDescriptor()
getDescriptor
in interface Describable<SCMNavigator>
getDescriptor
in class AbstractDescribableImpl<SCMNavigator>
@CheckForNull public String getPronoun()
SCMNavigator
. Must start with a capital letter.null
to fall back to the calling context's default.@NonNull public final List<Action> fetchActions(@NonNull SCMNavigatorOwner owner, @CheckForNull SCMNavigatorEvent event, @CheckForNull TaskListener listener) throws IOException, InterruptedException
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)
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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected List<Action> retrieveActions(@NonNull SCMNavigatorOwner owner, @CheckForNull SCMNavigatorEvent event, @NonNull TaskListener listener) throws IOException, InterruptedException
fetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener)
. Fetches any actions that
should be persisted for objects related to the specified owner.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.Action
instances to persist.IOException
- if an error occurs while performing the operation.InterruptedException
- if any thread has interrupted the current thread.@NonNull protected final TaskListener defaultListener(@CheckForNull TaskListener listener)
null
TaskListener
reference into a guaranteed non-null reference.listener
- a possibly null
TaskListener
reference.TaskListener
.protected final void checkInterrupt() throws InterruptedException
Thread.interrupted()
and throws an InterruptedException
if it was set.InterruptedException
- if interrupted.public void afterSave(@NonNull SCMNavigatorOwner owner)
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.owner
- the SCMNavigatorOwner
.Copyright © 2016–2022. All rights reserved.