Package 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

  • Field Details

  • Constructor Details

    • SCMNavigator

      protected SCMNavigator()
      Constructor.

  • Method Details

    • 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:

    • 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:

    • 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