[JENKINS-43507] Documenting SCMHeadAuthority

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

@@ -24,31 +24,126 @@
 
 package jenkins.scm.api.trait;
 
+import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.OverrideMustInvoke;
 import hudson.model.AbstractDescribableImpl;
 import java.io.IOException;
 import jenkins.scm.api.SCMHead;
+import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.mixin.SCMHeadMixin;
 
-public abstract class SCMHeadAuthority<S extends SCMSourceRequest, H extends SCMHeadMixin>
-        extends AbstractDescribableImpl<SCMHeadAuthority<?, ?>> {
+/**
+ * Abstraction to allow plugable definitions of trust for {@link SCMHead} and {@link SCMRevision} instances in the
+ * context of a specific {@link SCMSourceRequest}.
+ * <p>
+ * Note: there can be multiple authorities for the same types of head / revision active in the context of any one
+ * request. The ultimate trust state is determined by a logical OR operation, in other words if any one authority
+ * says that the head / revision is trusted then the head / revision is trusted.
+ *
+ * @param <S> the type of {@link SCMSourceRequest}.
+ * @param <H> the specialization of {@link SCMHeadMixin} that this authority provides trust information for.
+ * @param <R> the specialization of {@link SCMRevision} that this authority provides trust information for.
+ * @since 3.4.0
+ */
+public abstract class SCMHeadAuthority<S extends SCMSourceRequest, H extends SCMHeadMixin, R extends SCMRevision>
+        extends AbstractDescribableImpl<SCMHeadAuthority<?, ?, ?>> {
 
+    /**
+     * Checks if this authority is relevant to the supplied {@link SCMHead}.
+     *
+     * @param head the supplied {@link SCMHead}.
+     * @return {@code true} if and only if this authority can provide trust information for the supplied head.
+     */
     public final boolean isApplicableTo(@NonNull SCMHead head) {
         return getDescriptor().isApplicableToHead(head);
     }
 
+    /**
+     * Checks if this authority is relevant to the supplied {@link SCMRevision}.
+     *
+     * @param revision the supplied {@link SCMRevision}.
+     * @return {@code true} if and only if this authority can provide trust information for the supplied revision.
+     */
+    public final boolean isApplicableTo(@NonNull SCMRevision revision) {
+        return getDescriptor().isApplicableToRevision(revision);
+    }
+
+    /**
+     * Checks if this authority is relevant to the supplied {@link SCMSourceRequest}.
+     *
+     * @param request the supplied {@link SCMSourceRequest}.
+     * @return {@code true} if and only if this authority can provide trust information for the supplied requesy.
+     */
     public final boolean isApplicableTo(@NonNull SCMSourceRequest request) {
         return getDescriptor().isApplicableToRequest(request);
     }
 
+    /**
+     * Checks if the supplied {@link SCMHead} is trusted in the context of the specified {@link SCMSourceRequest}.
+     *
+     * @param request the {@link SCMSourceRequest}.
+     * @param head    the {@link SCMHead}.
+     * @return {@code true} if the supplied head is trusted.
+     * @throws IOException          if there was an I/O error trying to establish the trust status.
+     * @throws InterruptedException if interrupted while trying to establing the trust status.
+     */
     @SuppressWarnings("unchecked")
     public final boolean isTrusted(@NonNull SCMSourceRequest request, @NonNull SCMHead head)
             throws IOException, InterruptedException {
-        return isApplicableTo(request) && isApplicableTo(head) && checkTrusted((S) request, (H) head);
+        return isApplicableTo(request)
+                && isApplicableTo(head)
+                && checkTrusted((S) request, (H) head);
+    }
+
+    /**
+     * Checks if the supplied {@link SCMRevision} is trusted in the context of the specified {@link SCMSourceRequest}.
+     *
+     * @param request  the {@link SCMSourceRequest}.
+     * @param revision the {@link SCMRevision}.
+     * @return {@code true} if the supplied revision is trusted.
+     * @throws IOException          if there was an I/O error trying to establish the trust status.
+     * @throws InterruptedException if interrupted while trying to establing the trust status.
+     */
+    @SuppressWarnings("unchecked")
+    public final boolean isTrusted(@NonNull SCMSourceRequest request, @CheckForNull SCMRevision revision)
+            throws IOException, InterruptedException {
+        return isApplicableTo(request)
+                && isApplicableTo(revision.getHead())
+                && isApplicableTo(revision)
+                && checkTrusted((S) request, (H) revision);
     }
 
+    /**
+     * SPI: checks if the supplied {@link SCMHead} is trusted in the context of the supplied {@link SCMSourceRequest}.
+     *
+     * @param request the {@link SCMSourceRequest}.
+     * @param head    the {@link SCMHead}.
+     * @return {@code true} if trusted.
+     * @throws IOException          if there was an I/O error trying to establish the trust status.
+     * @throws InterruptedException if interrupted while trying to establing the trust status.
+     */
     protected abstract boolean checkTrusted(@NonNull S request, @NonNull H head) throws IOException, InterruptedException;
 
+    /**
+     * SPI: checks if the supplied {@link SCMRevision} is trusted in the context of the supplied
+     * {@link SCMSourceRequest}. Default implementation just calls {@link #checkTrusted(SCMSourceRequest, SCMHeadMixin)}
+     * with {@link SCMRevision#getHead()}.
+     *
+     * @param request  the {@link SCMSourceRequest}.
+     * @param revision the {@link SCMRevision}.
+     * @return {@code true} if trusted.
+     * @throws IOException          if there was an I/O error trying to establish the trust status.
+     * @throws InterruptedException if interrupted while trying to establing the trust status.
+     */
+    @OverrideMustInvoke
+    protected boolean checkTrusted(@NonNull S request, @NonNull R revision) throws IOException, InterruptedException {
+        return checkTrusted(request, (H) revision.getHead());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public SCMHeadAuthorityDescriptor getDescriptor() {
         return (SCMHeadAuthorityDescriptor) super.getDescriptor();

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

@@ -28,29 +28,61 @@
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import jenkins.scm.api.SCMHead;
+import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.mixin.SCMHeadMixin;
 import org.jvnet.tiger_types.Types;
 
-public abstract class SCMHeadAuthorityDescriptor extends Descriptor<SCMHeadAuthority<?, ?>> {
+/**
+ * {@link Descriptor} base class for {@link SCMHeadAuthority} implementations.
+ *
+ * @since 3.4.0
+ */
+public abstract class SCMHeadAuthorityDescriptor extends Descriptor<SCMHeadAuthority<?, ?, ?>> {
 
+    /**
+     * The {@link SCMSourceRequest} class.
+     */
     private final Class<? extends SCMSourceRequest> requestClass;
+    /**
+     * The {@link SCMHeadMixin} class.
+     */
     private final Class<? extends SCMHeadMixin> headClass;
+    /**
+     * The {@link SCMRevision} class.
+     */
+    private final Class<? extends SCMRevision> revisionClass;
 
-    protected SCMHeadAuthorityDescriptor(Class<? extends SCMHeadAuthority<?, ?>> clazz,
+    /**
+     * Constructor to use when type inferrence using {@link #SCMHeadAuthorityDescriptor()} does not work.
+     *
+     * @param clazz         Pass in the type of {@link SCMHeadAuthority}
+     * @param requestClass  the type of {@link SCMSourceRequest}.
+     * @param headClass     the type of {@link SCMHead}.
+     * @param revisionClass the type of {@link SCMRevision}.
+     */
+    protected SCMHeadAuthorityDescriptor(Class<? extends SCMHeadAuthority<?, ?, ?>> clazz,
                                          Class<? extends SCMSourceRequest> requestClass,
-                                         Class<? extends SCMHeadMixin> headClass) {
+                                         Class<? extends SCMHeadMixin> headClass,
+                                         Class<? extends SCMRevision> revisionClass) {
         super(clazz);
         this.requestClass = requestClass;
         this.headClass = headClass;
+        this.revisionClass = revisionClass;
     }
 
+    /**
+     * Infers the type of the corresponding {@link SCMHeadAuthority} from the outer class.
+     * This version works when you follow the common convention, where a descriptor
+     * is written as the static nested class of the describable class.
+     */
     protected SCMHeadAuthorityDescriptor() {
         Type bt = Types.getBaseClass(clazz, SCMHeadAuthority.class);
         if (bt instanceof ParameterizedType) {
             ParameterizedType pt = (ParameterizedType) bt;
             // this 'headClass' is the closest approximation of T of SCMHeadAuthority<T>.
             requestClass = Types.erasure(pt.getActualTypeArguments()[0]);
             headClass = Types.erasure(pt.getActualTypeArguments()[1]);
+            revisionClass = Types.erasure(pt.getActualTypeArguments()[2]);
             if (!SCMSourceRequest.class.isAssignableFrom(requestClass)) {
                 throw new AssertionError(
                         "Failed to correctly detect SCMSourceRequest specialization. Use the constructor that takes "
@@ -62,25 +94,75 @@ protected SCMHeadAuthorityDescriptor() {
                         "Failed to correctly detect SCMHead specialization. Use the constructor that takes the Class "
                                 + "objects explicitly");
             }
+            if (!SCMRevision.class.isAssignableFrom(revisionClass)) {
+                throw new AssertionError(
+                        "Failed to correctly detect SCMRevision specialization. Use the constructor that takes the "
+                                + "Class "
+                                + "objects explicitly");
+            }
         } else {
             throw new AssertionError(
                     "Failed to correctly detect specialization. Use the constructor that takes the Class objects "
                             + "explicitly");
         }
     }
 
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMHead}.
+     *
+     * @param head the {@link SCMHead}.
+     * @return {@code true} if applicable.
+     */
     public boolean isApplicableToHead(SCMHead head) {
         return isApplicableToHead(head.getClass());
     }
 
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied type of {@link SCMHead}.
+     *
+     * @param headClass the type of {@link SCMHead}.
+     * @return {@code true} if applicable.
+     */
     public boolean isApplicableToHead(Class<? extends SCMHead> headClass) {
         return this.headClass.isAssignableFrom(headClass);
     }
 
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMRevision}.
+     *
+     * @param revision the {@link SCMRevision}.
+     * @return {@code true} if applicable.
+     */
+    public boolean isApplicableToRevision(SCMRevision revision) {
+        return isApplicableToHead(revision.getHead()) && isApplicableToRevision(revision.getClass());
+    }
+
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied type of {@link SCMRevision}.
+     *
+     * @param revisionClass the type of {@link SCMRevision}.
+     * @return {@code true} if applicable.
+     */
+    public boolean isApplicableToRevision(Class<? extends SCMRevision> revisionClass) {
+        return this.revisionClass.isAssignableFrom(revisionClass);
+    }
+
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMSourceRequest}.
+     *
+     * @param request the {@link SCMSourceRequest}.
+     * @return {@code true} if applicable.
+     */
     public boolean isApplicableToRequest(SCMSourceRequest request) {
         return requestClass.isInstance(request);
     }
 
+    /**
+     * Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied type of {@link SCMSourceRequest}.
+     *
+     * @param requestClass the type of {@link SCMSourceRequest}.
+     * @return {@code true} if applicable.
+     */
     public boolean isApplicableToRequest(Class<? extends SCMSourceRequest> requestClass) {
         return this.requestClass.isAssignableFrom(requestClass);
     }