[JENKINS-16830] clarified the semantics

(03:21:10 PM) m2spring: kohsuke: BTW, what do you think about this Jira? https://issues.jenkins-ci.org/browse/JENKINS-16830
(03:21:13 PM) jenkins-admin: JENKINS-16830:RunnerAbortedException no longer workin in RunListener.onStartup() (Resolved) http://jenkins-ci.org/issue/16830
(03:23:01 PM) m2spring: kohsuke: The question is whether RunListener.onStart() is intended to be allowed to abort a build by throwing Run.RunnerAbortedException, or not.
(03:23:18 PM) kohsuke: still reading
(03:25:27 PM) kohsuke: m2spring: I can make it work for you
(03:25:42 PM) kohsuke: I guess you want RunnerAbortedException to be a pass-through, right?
(03:25:50 PM) m2spring: I'm using now RunListener.setupEnvironment().
(03:25:58 PM) m2spring: This works and makes also a lot of sense.
(03:26:36 PM) m2spring: I can also see that not allowing onStart() to abort a build can make sense.
(03:26:51 PM) m2spring: I just wanted to hear your take on this.
(03:27:05 PM) kohsuke: kutzi is right that onStart() wasn't really intended to affect the build
(03:27:15 PM) kohsuke: it really was meant for just notifying
(03:27:33 PM) m2spring: Thanks for the clarification.
(03:27:40 PM) kohsuke: but if this is important for someone, I'm OK with making it work.
(03:27:53 PM) kohsuke: In this case it sounds like you are OK with the current state, so I'll leave it as WONTFIX
(03:27:58 PM) m2spring: setupEnvironment() seems to be the right place.
(03:28:05 PM) m2spring: Yes. Thanks :-)
(03:28:18 PM) kohsuke: I'll mention that in setupEnvironment javadoc so that we know it's a committed semantics
(03:28:28 PM) m2spring: Agreed.

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

@@ -34,6 +34,7 @@ import hudson.model.BuildListener;
 import hudson.model.Environment;
 import hudson.model.JobProperty;
 import hudson.model.Run;
+import hudson.model.Run.RunnerAbortedException;
 import hudson.model.TaskListener;
 import jenkins.model.Jenkins;
 import hudson.scm.SCM;
@@ -86,6 +87,9 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
      *      The listener for this build. This can be used to produce log messages, for example,
      *      which becomes a part of the "console output" of this build. But when this method runs,
      *      the build is considered completed, so its status cannot be changed anymore.
+     * @throws RuntimeException
+     *      Any exception/error thrown from this method will be swallowed to prevent broken listeners
+     *      from breaking all the builds.
      */
     public void onCompleted(R r, @Nonnull TaskListener listener) {}
 
@@ -95,6 +99,10 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
      * <p>
      * At this point, all the records related to a build is written down to the disk. As such,
      * {@link TaskListener} is no longer available. This happens later than {@link #onCompleted(Run, TaskListener)}.
+     *
+     * @throws RuntimeException
+     *      Any exception/error thrown from this method will be swallowed to prevent broken listeners
+     *      from breaking all the builds.
      */
     public void onFinalized(R r) {}
 
@@ -107,6 +115,9 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
      * @param listener
      *      The listener for this build. This can be used to produce log messages, for example,
      *      which becomes a part of the "console output" of this build.
+     * @throws RuntimeException
+     *      Any exception/error thrown from this method will be swallowed to prevent broken listeners
+     *      from breaking all the builds.
      */
     public void onStarted(R r, TaskListener listener) {}
 
@@ -134,9 +145,12 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
      * @throws IOException
      *      terminates the build abnormally. Hudson will handle the exception
      *      and reports a nice error message.
+     * @throws RunnerAbortedException
+     *      If a fatal error is detected and the callee handled it gracefully, throw this exception
+     *      to suppress a stack trace by the receiver.
      * @since 1.410
      */
-    public Environment setUpEnvironment( AbstractBuild build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException {
+    public Environment setUpEnvironment( AbstractBuild build, Launcher launcher, BuildListener listener ) throws IOException, InterruptedException, RunnerAbortedException {
     	return new Environment() {};
     }
 
@@ -144,6 +158,9 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
      * Called right before a build is going to be deleted.
      *
      * @param r The build.
+     * @throws RuntimeException
+     *      Any exception/error thrown from this method will be swallowed to prevent broken listeners
+     *      from breaking all the builds.
      */
     public void onDeleted(R r) {}
 
@@ -194,7 +211,7 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
             if(l.targetType.isInstance(r))
                 try {
                     l.onStarted(r,listener);
-                } catch (Exception e) {
+                } catch (Throwable e) {
                     report(e);
                 }
         }
@@ -211,7 +228,7 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
             if(l.targetType.isInstance(r))
                 try {
                     l.onFinalized(r);
-                } catch (Exception e) {
+                } catch (Throwable e) {
                     report(e);
                 }
         }
@@ -225,7 +242,7 @@ public abstract class RunListener<R extends Run> implements ExtensionPoint {
             if(l.targetType.isInstance(r))
                 try {
                     l.onDeleted(r);
-                } catch (Exception e) {
+                } catch (Throwable e) {
                     report(e);
                 }
         }