[JENKINS-43507] Documentation drives code improvements

jenkinsci · May 3, 2017 · b7c5b5d3c00b608613e1915f8033ca608a72e542 · b7c5b5d
1 parent 4ce900a
commit b7c5b5d3c00b608613e1915f8033ca608a72e542
diff --git a/src/main/java/jenkins/scm/api/trait/SCMHeadAuthority.java b/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;
+  
+    }
+  
+
 }
diff --git a/src/main/java/jenkins/scm/api/trait/SCMHeadAuthorityDescriptor.java b/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;
+  
+    }
 }
diff --git a/src/main/java/jenkins/scm/api/trait/SCMHeadFilter.java b/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;

diff --git a/src/main/java/jenkins/scm/api/trait/SCMHeadPrefilter.java b/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);
 }
diff --git a/src/main/java/jenkins/scm/api/trait/SCMSourceFilter.java b/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;

diff --git a/src/main/java/jenkins/scm/api/trait/SCMSourcePrefilter.java b/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);
 }