[JENKINS-43507] Documentation drives code improvements

src/main/java/jenkins/scm/api/trait/SCMHeadAuthority.java

@@ -27,9 +27,14 @@
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.OverrideMustInvoke;
+import hudson.DescriptorExtensionList;
 import hudson.model.AbstractDescribableImpl;
 import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import jenkins.model.Jenkins;
 import jenkins.scm.api.SCMHead;
+import jenkins.scm.api.SCMHeadOrigin;
 import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.mixin.SCMHeadMixin;
 
@@ -148,4 +153,59 @@ protected boolean checkTrusted(@NonNull S request, @NonNull R revision) throws I
     public SCMHeadAuthorityDescriptor getDescriptor() {
         return (SCMHeadAuthorityDescriptor) super.getDescriptor();
     }
+
+    /**
+     * Returns a list of all {@link SCMHeadAuthorityDescriptor} instances.
+     *
+     * @return a list of all {@link SCMHeadAuthorityDescriptor} instances.
+     */
+    @SuppressWarnings("unchecked")
+    public static DescriptorExtensionList<SCMHeadAuthority<?, ?, ?>, SCMHeadAuthorityDescriptor> all() {
+        return (DescriptorExtensionList) Jenkins.getActiveInstance().getDescriptorList(SCMHeadAuthority.class);
+    }
+
+    /**
+     * Retursn the subset of {@link SCMHeadAuthorityDescriptor} instances applicable to the supplied criteria.
+     *
+     * @param requestClass  the {@link SCMSourceRequest} class (or {@code null} to match any).
+     * @param headClass     the {@link SCMHeadMixin} class (or {@code null} to match any).
+     * @param revisionClass the {@link SCMRevision} class (or {@code null} to match any).
+     * @param origins       the {@link SCMHeadOrigin} instances.
+     * @return the list of matching {@link SCMHeadAuthorityDescriptor} instances.
+     */
+    public static List<SCMHeadAuthorityDescriptor> _for(@CheckForNull Class<? extends SCMSourceRequest> requestClass,
+                                                        @CheckForNull Class<? extends SCMHeadMixin> headClass,
+                                                        @CheckForNull Class<? extends SCMRevision> revisionClass,
+                                                        Class<? extends SCMHeadOrigin>... origins) {
+        if (requestClass == null) {
+            requestClass = SCMSourceRequest.class;
+        }
+        if (headClass == null) {
+            headClass = SCMHeadMixin.class;
+        }
+        if (revisionClass == null) {
+            revisionClass = SCMRevision.class;
+        }
+        List<SCMHeadAuthorityDescriptor> result = new ArrayList<SCMHeadAuthorityDescriptor>();
+        for (SCMHeadAuthorityDescriptor d : all()) {
+            if (d.isApplicableToRequest(requestClass)
+                    && d.isApplicableToHead(headClass)
+                    && d.isApplicableToRevision(revisionClass)) {
+                boolean match = origins.length == 0;
+                if (!match) {
+                    for (Class<? extends SCMHeadOrigin> o : origins) {
+                        if (d.isApplicableToOrigin(o)) {
+                            match = true;
+                            break;
+                        }
+                    }
+                }
+                if (match) {
+                    result.add(d);
+                }
+            }
+        }
+        return result;
+    }
+
 }

src/main/java/jenkins/scm/api/trait/SCMHeadAuthorityDescriptor.java

@@ -24,10 +24,12 @@
 
 package jenkins.scm.api.trait;
 
+import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.model.Descriptor;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import jenkins.scm.api.SCMHead;
+import jenkins.scm.api.SCMHeadOrigin;
 import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.mixin.SCMHeadMixin;
 import org.jvnet.tiger_types.Types;
@@ -113,8 +115,8 @@ protected SCMHeadAuthorityDescriptor() {
      * @param head the {@link SCMHead}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToHead(SCMHead head) {
-        return isApplicableToHead(head.getClass());
+    public boolean isApplicableToHead(@NonNull SCMHead head) {
+        return isApplicableToHead(head.getClass()) && isApplicableToOrigin(head.getOrigin());
     }
 
     /**
@@ -123,7 +125,7 @@ public boolean isApplicableToHead(SCMHead head) {
      * @param headClass the type of {@link SCMHead}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToHead(Class<? extends SCMHead> headClass) {
+    public boolean isApplicableToHead(@NonNull Class<? extends SCMHeadMixin> headClass) {
         return this.headClass.isAssignableFrom(headClass);
     }
 
@@ -133,7 +135,7 @@ public boolean isApplicableToHead(Class<? extends SCMHead> headClass) {
      * @param revision the {@link SCMRevision}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToRevision(SCMRevision revision) {
+    public boolean isApplicableToRevision(@NonNull SCMRevision revision) {
         return isApplicableToHead(revision.getHead()) && isApplicableToRevision(revision.getClass());
     }
 
@@ -143,7 +145,7 @@ public boolean isApplicableToRevision(SCMRevision revision) {
      * @param revisionClass the type of {@link SCMRevision}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToRevision(Class<? extends SCMRevision> revisionClass) {
+    public boolean isApplicableToRevision(@NonNull Class<? extends SCMRevision> revisionClass) {
         return this.revisionClass.isAssignableFrom(revisionClass);
     }
 
@@ -153,7 +155,7 @@ public boolean isApplicableToRevision(Class<? extends SCMRevision> revisionClass
      * @param request the {@link SCMSourceRequest}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToRequest(SCMSourceRequest request) {
+    public boolean isApplicableToRequest(@NonNull SCMSourceRequest request) {
         return requestClass.isInstance(request);
     }
 
@@ -163,7 +165,27 @@ public boolean isApplicableToRequest(SCMSourceRequest request) {
      * @param requestClass the type of {@link SCMSourceRequest}.
      * @return {@code true} if applicable.
      */
-    public boolean isApplicableToRequest(Class<? extends SCMSourceRequest> requestClass) {
+    public boolean isApplicableToRequest(@NonNull Class<? extends SCMSourceRequest> requestClass) {
         return this.requestClass.isAssignableFrom(requestClass);
     }
+
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMHeadOrigin}.
+     *
+     * @param origin the {@link SCMHeadOrigin}.
+     * @return {@code true} if applicable.
+     */
+    public boolean isApplicableToOrigin(@NonNull SCMHeadOrigin origin) {
+        return isApplicableToOrigin(origin.getClass());
+    }
+
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMHeadOrigin}.
+     *
+     * @param originClass the type of {@link SCMHeadOrigin}.
+     * @return {@code true} if applicable.
+     */
+    public boolean isApplicableToOrigin(@NonNull Class<? extends SCMHeadOrigin> originClass) {
+        return true;
+    }
 }

src/main/java/jenkins/scm/api/trait/SCMHeadFilter.java

@@ -28,8 +28,26 @@
 import java.io.IOException;
 import jenkins.scm.api.SCMHead;
 
+/**
+ * A {@link SCMSourceRequest} dependent filter of {@link SCMHead} instances. Typically these filters may need to
+ * make remote requests in order to determine exclusion.
+ * If multiple filters are used, if any exclude then the head is excluded.
+ *
+ * @see SCMHeadPrefilter for {@link SCMSourceRequest} independent filters / filters that can perform completely
+ * off-line.
+ * @since 3.4.0
+ */
 public abstract class SCMHeadFilter {
 
+    /**
+     * Checks if the supplied {@link SCMHead} is excluded from the specified {@link SCMSourceRequest}.
+     *
+     * @param request the {@link SCMSourceRequest}.
+     * @param head    the {@link SCMHead}.
+     * @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
+     * @throws IOException          if there was an I/O error when determining exclusion.
+     * @throws InterruptedException if interrupted while determining exclusion.
+     */
     public abstract boolean isExcluded(@NonNull SCMSourceRequest request, @NonNull SCMHead head)
             throws IOException, InterruptedException;
 

src/main/java/jenkins/scm/api/trait/SCMHeadPrefilter.java

@@ -28,8 +28,25 @@
 import jenkins.scm.api.SCMHead;
 import jenkins.scm.api.SCMSource;
 
+/**
+ * A {@link SCMSourceRequest} independent filter of {@link SCMHead} instances. These filters may not make remote
+ * requests in order to determine exclusion.
+ * If multiple filters are used, if any exclude then the head is excluded.
+ * The {@link SCMHeadPrefilter} instances are applied before {@link SCMHeadFilter} instances in order to minimize
+ * remote requests.
+ *
+ * @see SCMHeadFilter for {@link SCMSourceRequest} dependent filters / filters that can may require on-line operation.
+ * @since 3.4.0
+ */
 public abstract class SCMHeadPrefilter {
 
+    /**
+     * Checks if the supplied {@link SCMHead} is excluded from the specified {@link SCMSource}.
+     *
+     * @param source the {@link SCMSource}.
+     * @param head   the {@link SCMHead}.
+     * @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
+     */
     public abstract boolean isExcluded(@NonNull SCMSource source, @NonNull SCMHead head);
 
 }

src/main/java/jenkins/scm/api/trait/SCMSourceFilter.java

@@ -27,8 +27,26 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import java.io.IOException;
 
+/**
+ * A {@link SCMNavigatorRequest} dependent filter of project names. Typically these filters may need to
+ * make remote requests in order to determine exclusion.
+ * If multiple filters are used, if any exclude then the project name is excluded.
+ *
+ * @see SCMSourcePrefilter for {@link SCMSourceRequest} independent filters / filters that can perform completely
+ * off-line.
+ * @since 3.4.0
+ */
 public abstract class SCMSourceFilter {
 
+    /**
+     * Checks if the supplied project name is excluded from the specified {@link SCMNavigatorRequest}.
+     *
+     * @param request     the {@link SCMNavigatorRequest}.
+     * @param projectName the project name.
+     * @return {@code true} if and only if the project name is excluded from the request.
+     * @throws IOException          if there was an I/O error when determining exclusion.
+     * @throws InterruptedException if interrupted while determining exclusion.
+     */
     public abstract boolean isExcluded(@NonNull SCMNavigatorRequest request, @NonNull String projectName)
             throws IOException, InterruptedException;
 

src/main/java/jenkins/scm/api/trait/SCMSourcePrefilter.java

@@ -25,10 +25,29 @@
 package jenkins.scm.api.trait;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
+import jenkins.scm.api.SCMHead;
 import jenkins.scm.api.SCMNavigator;
 
+/**
+ * A {@link SCMNavigatorRequest} independent filter of project names. These filters may not make remote
+ * requests in order to determine exclusion.
+ * If multiple filters are used, if any exclude then the project name is excluded.
+ * The {@link SCMSourcePrefilter} instances are applied before {@link SCMSourceFilter} instances in order to minimize
+ * remote requests.
+ *
+ * @see SCMSourceFilter for {@link SCMNavigatorRequest} dependent filters / filters that can may require on-line
+ * operation.
+ * @since 3.4.0
+ */
 public abstract class SCMSourcePrefilter {
 
+    /**
+     * Checks if the supplied project name is excluded from the specified {@link SCMNavigator}.
+     *
+     * @param source      the {@link SCMNavigator}.
+     * @param projectName the project name.
+     * @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
+     */
     public abstract boolean isExcluded(@NonNull SCMNavigator source, @NonNull String projectName);
 
 }