[JENKINS-43507] Allow extension plugins to disable notifications

src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubBuildStatusNotification.java

@@ -47,6 +47,7 @@
 import jenkins.model.Jenkins;
 import jenkins.plugins.git.AbstractGitSCMSource.SCMRevisionImpl;
 import jenkins.scm.api.SCMHead;
+import jenkins.scm.api.SCMHeadObserver;
 import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.SCMRevisionAction;
 import jenkins.scm.api.SCMSource;
@@ -180,14 +181,20 @@ private static GHRepository lookUpRepo(GitHub github, @NonNull Job<?,?> job) thr
      * Returns the GitHub Repository associated to a Job.
      *
      * @param job A {@link Job}
-     * @return A {@link GHRepository} or null, either if a scan credentials was not provided, or a GitHubSCMSource was not defined.
+     * @return A {@link GHRepository} or {@code null}, if any of: a credentials was not provided; notifications were
+     * disabled, or the job is not from a {@link GitHubSCMSource}.
      * @throws IOException
      */
     @CheckForNull
     private static GitHub lookUpGitHub(@NonNull Job<?,?> job) throws IOException {
         SCMSource src = SCMSource.SourceByItem.findSource(job);
         if (src instanceof GitHubSCMSource) {
             GitHubSCMSource source = (GitHubSCMSource) src;
+            if (new GitHubSCMSourceContext(null, SCMHeadObserver.none())
+                    .withTraits(source.getTraits())
+                    .notificationsDisabled()) {
+                return null;
+            }
             if (source.getScanCredentialsId() != null) {
                 return Connector.connect(source.getApiUri(), Connector.lookupScanCredentials
                         (job, null, source.getScanCredentialsId()));
@@ -221,6 +228,11 @@ public void onEnterWaiting(Queue.WaitingItem wi) {
             if (!(head instanceof PullRequestSCMHead)) {
                 return;
             }
+            if (new GitHubSCMSourceContext(null, SCMHeadObserver.none())
+                    .withTraits(((GitHubSCMSource) source).getTraits())
+                    .notificationsDisabled()) {
+                return;
+            }
             // prevent delays in the queue when updating github
             Computer.threadPoolForRemoting.submit(new Runnable() {
                 @Override
@@ -265,15 +277,15 @@ public void run() {
                     } catch (FileNotFoundException e) {
                         LOGGER.log(Level.WARNING,
                                 "Could not update commit status to PENDING. Valid scan credentials? Valid scopes?",
-                                LOGGER.isLoggable(Level.FINE) ? e : (Throwable)null);
+                                LOGGER.isLoggable(Level.FINE) ? e : null);
                     } catch (IOException e) {
                         LOGGER.log(Level.WARNING,
                                 "Could not update commit status to PENDING. Message: " + e.getMessage(),
-                                LOGGER.isLoggable(Level.FINE) ? e : (Throwable) null);
+                                LOGGER.isLoggable(Level.FINE) ? e : null);
                     } catch (InterruptedException e) {
                         LOGGER.log(Level.WARNING,
                                 "Could not update commit status to PENDING. Rate limit exhausted",
-                                LOGGER.isLoggable(Level.FINE) ? e : (Throwable) null);
+                                LOGGER.isLoggable(Level.FINE) ? e : null);
                         LOGGER.log(Level.FINE, null, e);
                     } finally {
                         Connector.release(gitHub);

src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMSourceContext.java

@@ -1,3 +1,26 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2017, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.plugins.github_branch_source;
 
 import edu.umd.cs.findbugs.annotations.CheckForNull;
@@ -11,81 +34,223 @@
 import jenkins.scm.api.mixin.ChangeRequestCheckoutStrategy;
 import jenkins.scm.api.trait.SCMSourceContext;
 
+/**
+ * The {@link SCMSourceContext} for GitHub.
+ *
+ * @since 2.2.0
+ */
 public class GitHubSCMSourceContext
         extends SCMSourceContext<GitHubSCMSourceContext, GitHubSCMSourceRequest> {
-
+    /**
+     * {@code true} if the {@link GitHubSCMSourceRequest} will need information about branches.
+     */
     private boolean wantBranches;
+    /**
+     * {@code true} if the {@link GitHubSCMSourceRequest} will need information about tags.
+     */
     private boolean wantTags;
+    /**
+     * {@code true} if the {@link GitHubSCMSourceRequest} will need information about origin pull requests.
+     */
     private boolean wantOriginPRs;
+    /**
+     * {@code true} if the {@link GitHubSCMSourceRequest} will need information about fork pull requests.
+     */
     private boolean wantForkPRs;
+    /**
+     * Set of {@link ChangeRequestCheckoutStrategy} to create for each origin pull request.
+     */
+    @NonNull
     private Set<ChangeRequestCheckoutStrategy> originPRStrategies = EnumSet.noneOf(ChangeRequestCheckoutStrategy.class);
+    /**
+     * Set of {@link ChangeRequestCheckoutStrategy} to create for each fork pull request.
+     */
+    @NonNull
     private Set<ChangeRequestCheckoutStrategy> forkPRStrategies = EnumSet.noneOf(ChangeRequestCheckoutStrategy.class);
+    /**
+     * {@code true} if notifications should be disabled in this context.
+     */
+    private boolean notificationsDisabled;
 
+    /**
+     * Constructor.
+     *
+     * @param criteria (optional) criteria.
+     * @param observer the {@link SCMHeadObserver}.
+     */
     public GitHubSCMSourceContext(@CheckForNull SCMSourceCriteria criteria, @NonNull SCMHeadObserver observer) {
         super(criteria, observer);
     }
 
-    @NonNull
-    @Override
-    public GitHubSCMSourceRequest newRequest(@NonNull SCMSource source, @CheckForNull TaskListener listener) {
-        return new GitHubSCMSourceRequest(source, this, listener);
-    }
-
-    public boolean wantBranches() {
+    /**
+     * Returns {@code true} if the {@link GitHubSCMSourceRequest} will need information about branches.
+     *
+     * @return {@code true} if the {@link GitHubSCMSourceRequest} will need information about branches.
+     */
+    public final boolean wantBranches() {
         return wantBranches;
     }
 
-    public boolean wantTags() {
+    /**
+     * Returns {@code true} if the {@link GitHubSCMSourceRequest} will need information about tags.
+     *
+     * @return {@code true} if the {@link GitHubSCMSourceRequest} will need information about tags.
+     */
+    public final boolean wantTags() {
         return wantTags;
     }
 
-    public boolean wantPRs() {
+    /**
+     * Returns {@code true} if the {@link GitHubSCMSourceRequest} will need information about pull requests.
+     *
+     * @return {@code true} if the {@link GitHubSCMSourceRequest} will need information about pull requests.
+     */
+    public final boolean wantPRs() {
         return wantOriginPRs || wantForkPRs;
     }
 
-    public boolean wantOriginPRs() {
+    /**
+     * Returns {@code true} if the {@link GitHubSCMSourceRequest} will need information about origin pull requests.
+     *
+     * @return {@code true} if the {@link GitHubSCMSourceRequest} will need information about origin pull requests.
+     */
+    public final boolean wantOriginPRs() {
         return wantOriginPRs;
     }
 
-    public boolean wantForkPRs() {
+    /**
+     * Returns {@code true} if the {@link GitHubSCMSourceRequest} will need information about fork pull requests.
+     *
+     * @return {@code true} if the {@link GitHubSCMSourceRequest} will need information about fork pull requests.
+     */
+    public final boolean wantForkPRs() {
         return wantForkPRs;
     }
 
-    public Set<ChangeRequestCheckoutStrategy> originPRStrategies() {
+
+    /**
+     * Returns the set of {@link ChangeRequestCheckoutStrategy} to create for each origin pull request.
+     *
+     * @return the set of {@link ChangeRequestCheckoutStrategy} to create for each origin pull request.
+     */
+    @NonNull
+    public final Set<ChangeRequestCheckoutStrategy> originPRStrategies() {
         return originPRStrategies;
     }
 
-    public Set<ChangeRequestCheckoutStrategy> forkPRStrategies() {
+    /**
+     * Returns the set of {@link ChangeRequestCheckoutStrategy} to create for each fork pull request.
+     *
+     * @return the set of {@link ChangeRequestCheckoutStrategy} to create for each fork pull request.
+     */
+    @NonNull
+    public final Set<ChangeRequestCheckoutStrategy> forkPRStrategies() {
         return forkPRStrategies;
     }
 
+    /**
+     * Returns {@code true} if notifications shoule be disabled.
+     *
+     * @return {@code true} if notifications shoule be disabled.
+     */
+    public final boolean notificationsDisabled() {
+        return notificationsDisabled;
+    }
+
+    /**
+     * Adds a requirement for branch details to any {@link GitHubSCMSourceContext} for this context.
+     *
+     * @param include {@code true} to add the requirement or {@code false} to leave the requirement as is (makes
+     *                simpler with method chaining)
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext wantBranches(boolean include) {
         wantBranches = wantBranches || include;
         return this;
     }
 
+    /**
+     * Adds a requirement for tag details to any {@link GitHubSCMSourceContext} for this context.
+     *
+     * @param include {@code true} to add the requirement or {@code false} to leave the requirement as is (makes
+     *                simpler with method chaining)
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext wantTags(boolean include) {
         wantTags = wantTags || include;
         return this;
     }
 
+    /**
+     * Adds a requirement for origin pull request details to any {@link GitHubSCMSourceContext} for this context.
+     *
+     * @param include {@code true} to add the requirement or {@code false} to leave the requirement as is (makes
+     *                simpler with method chaining)
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext wantOriginPRs(boolean include) {
         wantOriginPRs = wantOriginPRs || include;
         return this;
     }
 
+    /**
+     * Adds a requirement for fork pull request details to any {@link GitHubSCMSourceContext} for this context.
+     *
+     * @param include {@code true} to add the requirement or {@code false} to leave the requirement as is (makes
+     *                simpler with method chaining)
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext wantForkPRs(boolean include) {
         wantForkPRs = wantForkPRs || include;
         return this;
     }
 
+    /**
+     * Defines the {@link ChangeRequestCheckoutStrategy} instances to create for each origin pull request.
+     *
+     * @param strategies the strategies.
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext withOriginPRStrategies(Set<ChangeRequestCheckoutStrategy> strategies) {
         originPRStrategies.addAll(strategies);
         return this;
     }
 
+    /**
+     * Defines the {@link ChangeRequestCheckoutStrategy} instances to create for each fork pull request.
+     *
+     * @param strategies the strategies.
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
     public GitHubSCMSourceContext withForkPRStrategies(Set<ChangeRequestCheckoutStrategy> strategies) {
         forkPRStrategies.addAll(strategies);
         return this;
     }
+
+    /**
+     * Defines the notification mode to use in this context.
+     *
+     * @param disabled {@code true} to disable automatic notifications.
+     * @return {@code this} for method chaining.
+     */
+    @NonNull
+    public final GitHubSCMSourceContext withNotificationsDisabled(boolean disabled) {
+        this.notificationsDisabled = disabled;
+        return this;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @NonNull
+    @Override
+    public GitHubSCMSourceRequest newRequest(@NonNull SCMSource source, @CheckForNull TaskListener listener) {
+        return new GitHubSCMSourceRequest(source, this, listener);
+    }
 }