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 discoveredSCMSource
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.- 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 Description static AlternativeUiTextProvider.Message<SCMNavigator>
PRONOUN
Replaceable pronoun of that points to aSCMNavigator
.
-
Constructor Summary
Constructors Modifier Constructor Description protected
SCMNavigator()
Constructor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
afterSave(SCMNavigatorOwner owner)
Callback from theSCMNavigatorOwner
after theSCMNavigatorOwner
has been saved.protected void
checkInterrupt()
Checks theThread.interrupted()
and throws anInterruptedException
if it was set.protected TaskListener
defaultListener(TaskListener listener)
Turns a possiblynull
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 ofSCMSourceCategory
that thisSCMNavigator
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 ofSCMNavigator
.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 thisSCMNavigator
.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).
-
-
-
Field Detail
-
PRONOUN
public static final AlternativeUiTextProvider.Message<SCMNavigator> PRONOUN
Replaceable pronoun of that points to aSCMNavigator
. Defaults tonull
depending on the context.- Since:
- 2.0
-
-
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 fromfetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener)
should be not just equivalent butList.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 usingDataBoundSetter
on fields that affect theid()
calculation then those fields must callresetId()
if they may have invalidated the cachedgetId()
.- Since:
- 2.0.1
-
id
@NonNull protected abstract String id()
Generates the ID of the thing being navigated from the configuration of thisSCMNavigator
.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 fromfetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener)
should be not just equivalent butList.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.
-
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 theobserver
or its child callbacks. It is vitally important that implementations must periodically callcheckInterrupt()
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 failsInterruptedException
- 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 theobserver
or its child callbacks. It is vitally important that implementations must periodically callcheckInterrupt()
otherwise it will be impossible for users to interrupt the operation.- Parameters:
observer
- a recipient of progress notifications and a source of contextual informationevent
- the event from which the operation should be scoped.- Throws:
IOException
- if scanning failsInterruptedException
- 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 theobserver
or its child callbacks. It is vitally important that implementations must periodically callcheckInterrupt()
otherwise it will be impossible for users to interrupt the operation.- Parameters:
observer
- a recipient of progress notifications and a source of contextual informationevent
- the event from which the operation should be scoped.- Throws:
IOException
- if scanning failsInterruptedException
- 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 theobserver
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 failsInterruptedException
- if scanning is interrupted- Since:
- 2.0
-
getCategories
@NonNull public final Set<? extends SCMSourceCategory> getCategories()
Returns the set ofSCMSourceCategory
that thisSCMNavigator
supports. There will always be exactly oneSCMCategory.isUncategorized()
instance in the returned set.- Returns:
- the set of
SCMSourceCategory
that thisSCMNavigator
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 thisSCMNavigator
instance.- Since:
- 2.0
-
getDescriptor
public SCMNavigatorDescriptor getDescriptor()
- Specified by:
getDescriptor
in interfaceDescribable<SCMNavigator>
- Overrides:
getDescriptor
in classAbstractDescribableImpl<SCMNavigator>
-
getPronoun
@CheckForNull public String getPronoun()
Get the term used in the UI to represent this kind ofSCMNavigator
. 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 aItem
owns a specificSCMNavigator
, then this method would be called to refresh anyAction
instances of thatItem
.It is the responsibility of the caller to ensure that these
Action
instances are exposed on theItem
for example by providing aTransientActionFactory
implementation that reports these persisted actions separately (for exampleAbstractProject.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 theActionable.getAllActions()
through aTransientActionFactory
ignoring the cognitive dissonance triggered by adding non-transient actions through a transient action factory... think of it instead as aTemporalActionFactory
that adds actions that can change over time)- Parameters:
owner
- the owner of thisSCMNavigator
.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 forfetchActions(SCMNavigatorOwner, SCMNavigatorEvent, TaskListener)
. Fetches any actions that should be persisted for objects related to the specified owner.- Parameters:
owner
- the owner of thisSCMNavigator
.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 possiblynull
TaskListener
reference into a guaranteed non-null reference.- Parameters:
listener
- a possiblynull
TaskListener
reference.- Returns:
- guaranteed non-null
TaskListener
.
-
checkInterrupt
protected final void checkInterrupt() throws InterruptedException
Checks theThread.interrupted()
and throws anInterruptedException
if it was set.- Throws:
InterruptedException
- if interrupted.- Since:
- 2.0
-
afterSave
public void afterSave(@NonNull SCMNavigatorOwner owner)
Callback from theSCMNavigatorOwner
after theSCMNavigatorOwner
has been saved. Can be used to register theSCMNavigatorOwner
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
- theSCMNavigatorOwner
.- Since:
- 2.0
-
-