[JENKINS-43507] RequestBuilder -> Context

src/main/java/jenkins/scm/api/SCMBuilder.java

@@ -2,7 +2,6 @@
 
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
-import hudson.model.TaskListener;
 import hudson.scm.SCM;
 import hudson.scm.SCMDescriptor;
 import java.util.Arrays;
@@ -34,7 +33,7 @@ public SCMRevision getRevision() {
 
     @SuppressWarnings("unchecked")
     public B withTrait(@NonNull SCMSourceTrait trait) {
-        trait.applyToSCM((B)this);
+        trait.applyToBuilder((B)this);
         return (B) this;
     }
 

src/main/java/jenkins/scm/api/mixin/ChangeRequestSCMRevision.java

@@ -111,7 +111,10 @@ public final boolean equals(Object o) {
         if (!equivalent(that)) {
             return false;
         }
-        return !isMerge() || target.equals(that.target);
+        if (isMerge() && that.isMerge()) {
+            return target.equals(that.target);
+        }
+        return isMerge() == that.isMerge();
     }
 
     /**

src/main/java/jenkins/scm/api/trait/SCMSourceRequestBuilder.java → src/main/java/jenkins/scm/api/trait/SCMSourceContext.java

@@ -33,12 +33,22 @@
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
+import jenkins.scm.api.SCMHeadEvent;
 import jenkins.scm.api.SCMHeadObserver;
 import jenkins.scm.api.SCMSource;
 import jenkins.scm.api.SCMSourceCriteria;
 
-public abstract class SCMSourceRequestBuilder<B extends SCMSourceRequestBuilder<B, R>, R extends SCMSourceRequest> {
-    private final SCMSource source;
+/**
+ * Represents the context within which a {@link SCMSource} is processing requests. In general this is used as a builder
+ * for {@link SCMSourceRequest} instances through {@link SCMSourceContext#newRequest(SCMSource, TaskListener)} but there
+ * are some cases (such as {@link SCMHeadEvent} processing) where only the context is required and as such this
+ * type will be instantiated to obtain the context but no {@link SCMSourceRequest} will be created.
+ *
+ * @param <C> the type of {@link SCMSourceContext}
+ * @param <R> the type of {@link SCMSourceRequest} produced by this context.
+ * @since 2.2.0
+ */
+public abstract class SCMSourceContext<C extends SCMSourceContext<C, R>, R extends SCMSourceRequest> {
     @NonNull
     private final List<SCMSourceCriteria> criteria = new ArrayList<SCMSourceCriteria>();
     @NonNull
@@ -50,70 +60,68 @@
     @NonNull
     private SCMHeadObserver observer;
 
-    public SCMSourceRequestBuilder(@NonNull SCMSource source, @CheckForNull SCMSourceCriteria criteria,
-                                   @NonNull SCMHeadObserver observer) {
-        this.source = source;
+    public SCMSourceContext(@CheckForNull SCMSourceCriteria criteria, @NonNull SCMHeadObserver observer) {
         withCriteria(criteria);
         this.observer = observer;
     }
 
     @SuppressWarnings("unchecked")
-    public B withCriteria(@CheckForNull SCMSourceCriteria criteria) {
+    public C withCriteria(@CheckForNull SCMSourceCriteria criteria) {
         if (criteria != null) {
             this.criteria.add(criteria);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @SuppressWarnings("unchecked")
-    public B withAuthority(@CheckForNull SCMHeadAuthority authority) {
+    public C withAuthority(@CheckForNull SCMHeadAuthority authority) {
         if (authority != null) {
             this.authorities.add(authority);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @SuppressWarnings("unchecked")
-    public B withFilter(@CheckForNull SCMHeadFilter filter) {
+    public C withFilter(@CheckForNull SCMHeadFilter filter) {
         if (filter != null) {
             this.filters.add(filter);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @SuppressWarnings("unchecked")
-    public B withPrefilter(@CheckForNull SCMHeadPrefilter prefilter) {
+    public C withPrefilter(@CheckForNull SCMHeadPrefilter prefilter) {
         if (prefilter != null) {
             this.prefilters.add(prefilter);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @SuppressWarnings("unchecked")
-    public B withPrefilters(@CheckForNull Collection<SCMHeadPrefilter> prefilters) {
+    public C withPrefilters(@CheckForNull Collection<SCMHeadPrefilter> prefilters) {
         if (prefilters != null) {
             this.prefilters.addAll(prefilters);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @SuppressWarnings("unchecked")
-    public B withTrait(@NonNull SCMSourceTrait trait) {
+    public C withTrait(@NonNull SCMSourceTrait trait) {
         observer = trait.applyToObserver(observer);
-        trait.applyToRequest((B) this);
-        return (B) this;
+        trait.applyToContext(this);
+        return (C) this;
     }
 
-    public B withTraits(@NonNull SCMSourceTrait... traits) {
+    public C withTraits(@NonNull SCMSourceTrait... traits) {
         return withTraits(Arrays.asList(traits));
     }
 
     @SuppressWarnings("unchecked")
-    public B withTraits(@NonNull Collection<SCMSourceTrait> traits) {
+    public C withTraits(@NonNull Collection<SCMSourceTrait> traits) {
         for (SCMSourceTrait trait : traits) {
             withTrait(trait);
         }
-        return (B) this;
+        return (C) this;
     }
 
     @NonNull
@@ -141,9 +149,5 @@ public SCMHeadObserver observer() {
         return Collections.unmodifiableList(authorities);
     }
 
-    public SCMSource source() {
-        return source;
-    }
-
-    public abstract R build(@NonNull TaskListener listener);
+    public abstract R newRequest(@NonNull SCMSource source, @CheckForNull TaskListener listener);
 }

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

@@ -29,6 +29,7 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 import hudson.model.TaskListener;
+import hudson.util.LogTaskListener;
 import java.io.Closeable;
 import java.io.IOException;
 import java.lang.reflect.InvocationTargetException;
@@ -37,6 +38,8 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Set;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 import jenkins.scm.api.SCMHead;
 import jenkins.scm.api.SCMHeadEvent;
 import jenkins.scm.api.SCMHeadObserver;
@@ -55,7 +58,7 @@
 public abstract class SCMSourceRequest implements Closeable {
 
     /**
-     * The {@link SCMSource} making the request.
+     * The {@link SCMSource} to use when applying the {@link #prefilters}.
      */
     @NonNull
     private final SCMSource source;
@@ -115,20 +118,42 @@
     /**
      * Constructor.
      *
-     * @param builder  the builder.
-     * @param listener the {@link TaskListener}.
+     * @param source  the source.
+     * @param context  the context.
+     * @param listener the (optional) {@link TaskListener}.
      */
-    protected SCMSourceRequest(@NonNull SCMSourceRequestBuilder<?, ?> builder, @NonNull TaskListener listener) {
-        this.source = builder.source();
-        this.filters = Collections.unmodifiableList(new ArrayList<SCMHeadFilter>(builder.filters()));
-        this.prefilters = Collections.unmodifiableList(new ArrayList<SCMHeadPrefilter>(builder.prefilters()));
-        this.authorities = Collections.unmodifiableList(new ArrayList<SCMHeadAuthority>(builder.authorities()));
-        this.criteria = builder.criteria().isEmpty()
+    protected SCMSourceRequest(@NonNull SCMSource source, @NonNull SCMSourceContext<?, ?> context,
+                               @CheckForNull TaskListener listener) {
+        this.source = source;
+        this.filters = Collections.unmodifiableList(new ArrayList<SCMHeadFilter>(context.filters()));
+        this.prefilters = Collections.unmodifiableList(new ArrayList<SCMHeadPrefilter>(context.prefilters()));
+        this.authorities = Collections.unmodifiableList(new ArrayList<SCMHeadAuthority>(context.authorities()));
+        this.criteria = context.criteria().isEmpty()
                 ? Collections.<SCMSourceCriteria>emptyList()
-                : Collections.unmodifiableList(new ArrayList<SCMSourceCriteria>(builder.criteria()));
-        this.observer = builder.observer();
+                : Collections.unmodifiableList(new ArrayList<SCMSourceCriteria>(context.criteria()));
+        this.observer = context.observer();
         this.observerIncludes = observer.getIncludes();
-        this.listener = listener;
+        this.listener = defaultListener(listener);
+    }
+
+    /**
+     * Turns a possibly {@code null} {@link TaskListener} reference into a guaranteed non-null reference.
+     *
+     * @param listener a possibly {@code null} {@link TaskListener} reference.
+     * @return guaranteed non-null {@link TaskListener}.
+     */
+    @NonNull
+    private TaskListener defaultListener(@CheckForNull TaskListener listener) {
+        if (listener == null) {
+            Level level;
+            try {
+                level = Level.parse(System.getProperty(getClass().getName() + ".defaultListenerLevel", "FINE"));
+            } catch (IllegalArgumentException e) {
+                level = Level.FINE;
+            }
+            return new LogTaskListener(Logger.getLogger(getClass().getName()), level);
+        }
+        return listener;
     }
 
     /**
@@ -391,16 +416,6 @@ public void close() throws IOException {
         }
     }
 
-    /**
-     * Returns the {@link SCMSource} making this request.
-     *
-     * @return the {@link SCMSource} making this request.
-     */
-    @NonNull
-    public SCMSource source() {
-        return source;
-    }
-
     public interface RevisionFactory<H extends SCMHead, R extends SCMRevision> {
         @NonNull
         R create(@NonNull H head) throws IOException, InterruptedException;