[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;