massaging the change a bit.

- doc improvement
- report the result and the problem to the listener

core/src/main/java/hudson/model/AbstractProject.java

@@ -45,7 +45,6 @@ import hudson.model.Descriptor.FormException;
 import hudson.model.Fingerprint.RangeSet;
 import hudson.model.Queue.Executable;
 import hudson.model.Queue.Task;
-import hudson.model.listeners.SCMListener;
 import hudson.model.queue.SubTask;
 import hudson.model.Queue.WaitingItem;
 import hudson.model.RunMap.Constructor;
@@ -56,7 +55,6 @@ import hudson.model.queue.CauseOfBlockage;
 import hudson.model.queue.SubTaskContributor;
 import hudson.scm.ChangeLogSet;
 import hudson.scm.ChangeLogSet.Entry;
-import hudson.scm.NullChangeLogParser;
 import hudson.scm.NullSCM;
 import hudson.scm.PollingResult;
 import hudson.scm.SCM;
@@ -79,7 +77,6 @@ import hudson.util.AlternativeUiTextProvider.Message;
 import hudson.util.DescribableList;
 import hudson.util.EditDistance;
 import hudson.util.FormValidation;
-import hudson.util.IOException2;
 import hudson.widgets.BuildHistoryWidget;
 import hudson.widgets.HistoryWidget;
 import jenkins.model.Jenkins;
@@ -91,7 +88,6 @@ import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 import org.kohsuke.args4j.Argument;
 import org.kohsuke.args4j.CmdLineException;
-import org.kohsuke.stapler.AncestorInPath;
 import org.kohsuke.stapler.ForwardToView;
 import org.kohsuke.stapler.HttpRedirect;
 import org.kohsuke.stapler.HttpResponse;
@@ -105,8 +101,6 @@ import org.kohsuke.stapler.interceptor.RequirePOST;
 import javax.servlet.ServletException;
 import java.io.File;
 import java.io.IOException;
-import java.io.InterruptedIOException;
-import java.lang.ref.WeakReference;
 import java.lang.reflect.InvocationTargetException;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -1317,12 +1311,38 @@ public abstract class AbstractProject<P extends AbstractProject<P,R>,R extends A
             // as action, so we need to compute it. This happens later.
         }
 
-        try {
         try {
             SCMPollListener.fireBeforePolling(this, listener);
-        	} catch( Exception e ) {
-        		/* Make sure, that the listeners do not have any impact on the actual poll */
+            PollingResult r = _poll(listener, scm, lb);
+            SCMPollListener.firePollingSuccess(this,listener, r);
+            return r;
+        } catch (AbortException e) {
+            listener.getLogger().println(e.getMessage());
+            listener.fatalError(Messages.AbstractProject_Aborted());
+            LOGGER.log(Level.FINE, "Polling "+this+" aborted",e);
+            SCMPollListener.firePollingFailed(this, listener,e);
+            return NO_CHANGES;
+        } catch (IOException e) {
+            e.printStackTrace(listener.fatalError(e.getMessage()));
+            SCMPollListener.firePollingFailed(this, listener,e);
+            return NO_CHANGES;
+        } catch (InterruptedException e) {
+            e.printStackTrace(listener.fatalError(Messages.AbstractProject_PollingABorted()));
+            SCMPollListener.firePollingFailed(this, listener,e);
+            return NO_CHANGES;
+        } catch (RuntimeException e) {
+            SCMPollListener.firePollingFailed(this, listener,e);
+            throw e;
+        } catch (Error e) {
+            SCMPollListener.firePollingFailed(this, listener,e);
+            throw e;
+        }
     }
+
+    /**
+     * {@link #poll(TaskListener)} method without the try/catch block that does listener notification and .
+     */
+    private PollingResult _poll(TaskListener listener, SCM scm, R lb) throws IOException, InterruptedException {
         if (scm.requiresWorkspaceForPolling()) {
             // lock the workspace of the last build
             FilePath ws=lb.getWorkspace();
@@ -1377,25 +1397,6 @@ public abstract class AbstractProject<P extends AbstractProject<P,R>,R extends A
             pollingBaseline = r.remote;
             return r;
         }
-        } catch (AbortException e) {
-            listener.getLogger().println(e.getMessage());
-            listener.fatalError(Messages.AbstractProject_Aborted());
-            LOGGER.log(Level.FINE, "Polling "+this+" aborted",e);
-            return NO_CHANGES;
-        } catch (IOException e) {
-            e.printStackTrace(listener.fatalError(e.getMessage()));
-            return NO_CHANGES;
-        } catch (InterruptedException e) {
-            e.printStackTrace(listener.fatalError(Messages.AbstractProject_PollingABorted()));
-            return NO_CHANGES;
-        } finally {
-        	/* Do this no matter what */
-        	try {
-        		SCMPollListener.fireAfterPolling(this, listener);
-        	} catch( Exception e ) {
-        		/* Make sure, that the listeners do not have any impact on the actual poll */
-        	}
-        }
     }
 
     private boolean workspaceOffline(R build) throws IOException, InterruptedException {

core/src/main/java/hudson/model/listeners/SCMPollListener.java

@@ -25,25 +25,75 @@ package hudson.model.listeners;
 
 import hudson.ExtensionList;
 import hudson.ExtensionPoint;
+import hudson.scm.PollingResult;
 import jenkins.model.Jenkins;
 import hudson.model.AbstractProject;
 import hudson.model.TaskListener;
 
-public abstract class SCMPollListener implements ExtensionPoint {
+import java.io.IOException;
 
+/**
+ * A hook for listening to polling activities in Jenkins.
+ *
+ * @author Christian Wolfgang
+ * @author Kohsuke Kawaguchi
+ * @since 1.474
+ */
+public abstract class SCMPollListener implements ExtensionPoint {
+    /**
+     * Called before the polling execution.
+     *
+     * @param project
+     *      Project that's about to run polling.
+     * @param listener
+     *      Connected to the polling log.
+     */
 	public void onBeforePolling( AbstractProject<?, ?> project, TaskListener listener ) {}
 
-	public void onAfterPolling( AbstractProject<?, ?> project, TaskListener listener ) {}
+    /**
+     * Called when the polling successfully concluded.
+     *
+     * @param result
+     *      The result of the polling.
+     */
+	public void onPollingSuccess( AbstractProject<?, ?> project, TaskListener listener, PollingResult result) {}
+
+    /**
+     * Called when the polling concluded with an error.
+     *
+     * @param exception
+     *      The problem reported. This can include {@link InterruptedException} (that corresponds to the user cancelling it),
+     *      some anticipated problems like {@link IOException}, or bug in the code ({@link RuntimeException})
+     */
+    public void onPollingFailed( AbstractProject<?, ?> project, TaskListener listener, Throwable exception) {}
 
 	public static void fireBeforePolling( AbstractProject<?, ?> project, TaskListener listener ) {
+        for (SCMPollListener l : all()) {
+            try {
+                l.onBeforePolling(project, listener);
+            } catch (Exception e) {
+                /* Make sure, that the listeners do not have any impact on the actual poll */
+            }
+        }
+    }
+
+	public static void firePollingSuccess( AbstractProject<?, ?> project, TaskListener listener, PollingResult result ) {
 		for( SCMPollListener l : all() ) {
-			l.onBeforePolling( project, listener );
+            try {
+                l.onPollingSuccess(project, listener, result);
+            } catch (Exception e) {
+                /* Make sure, that the listeners do not have any impact on the actual poll */
+            }
 		}
 	}
 
-	public static void fireAfterPolling( AbstractProject<?, ?> project, TaskListener listener ) {
+    public static void firePollingFailed( AbstractProject<?, ?> project, TaskListener listener, Throwable exception ) {
    		for( SCMPollListener l : all() ) {
-			l.onAfterPolling( project, listener );
+               try {
+                   l.onPollingFailed(project, listener, exception);
+               } catch (Exception e) {
+                   /* Make sure, that the listeners do not have any impact on the actual poll */
+               }
    		}
    	}