Merge pull request akka#418 from akka/wip-2020-throws-clause-for-java…

…-api-√

akka#2020 - Adding 'checkedApply' to Mapper to allow for binary compatible r...

akka-actor-tests/src/test/java/akka/dispatch/JavaFutureTests.java

@@ -10,6 +10,8 @@
 import org.junit.BeforeClass;
 import org.junit.Test;
 import static org.junit.Assert.*;
+
+import java.io.IOException;
 import java.util.concurrent.Callable;
 import java.util.LinkedList;
 import java.lang.Iterable;
@@ -130,7 +132,8 @@ public void mustBeAbleToFlatMapAFuture() throws Throwable {
     cf.success("1000");
     Future<String> f = cf;
     Future<Integer> r = f.flatMap(new Mapper<String, Future<Integer>>() {
-      public Future<Integer> apply(String r) {
+      public Future<Integer> checkedApply(String r) throws Throwable {
+        if (false) throw new IOException("Just here to make sure this compiles.");
         latch.countDown();
         Promise<Integer> cf = Futures.promise(system.dispatcher());
         cf.success(Integer.parseInt(r));

akka-actor/src/main/scala/akka/dispatch/Future.scala

@@ -1006,6 +1006,7 @@ abstract class OnSuccess[-T] extends japi.CallbackBridge[T] {
    * This method will be invoked once when/if a Future that this callback is registered on
    * becomes successfully completed
    */
+  @throws(classOf[Throwable])
   def onSuccess(result: T): Unit
 }
 
@@ -1022,6 +1023,7 @@ abstract class OnFailure extends japi.CallbackBridge[Throwable] {
    * This method will be invoked once when/if a Future that this callback is registered on
    * becomes completed with a failure
    */
+  @throws(classOf[Throwable])
   def onFailure(failure: Throwable): Unit
 }
 
@@ -1042,6 +1044,7 @@ abstract class OnComplete[-T] extends japi.CallbackBridge[Either[Throwable, T]]
    * becomes completed with a failure or a success.
    * In the case of success then "failure" will be null, and in the case of failure the "success" will be null.
    */
+  @throws(classOf[Throwable])
   def onComplete(failure: Throwable, success: T): Unit
 }
 
@@ -1112,6 +1115,7 @@ abstract class Foreach[-T] extends japi.UnitFunctionBridge[T] {
    * This method will be invoked once when/if a Future that this callback is registered on
    * becomes successfully completed
    */
+  @throws(classOf[Throwable])
   def each(result: T): Unit
 }
 
@@ -1120,8 +1124,25 @@ abstract class Foreach[-T] extends japi.UnitFunctionBridge[T] {
  * if the Future that this callback is registered on becomes completed with a success.
  * This callback is the equivalent of an akka.japi.Function
  *
+ * Override "apply" normally, or "checkedApply" if you need to throw checked exceptions.
+ *
  * SAM (Single Abstract Method) class
  *
  * Java API
  */
-abstract class Mapper[-T, +R] extends scala.runtime.AbstractFunction1[T, R]
+abstract class Mapper[-T, +R] extends scala.runtime.AbstractFunction1[T, R] {
+
+  /**
+   * Override this method to perform the map operation, by default delegates to "checkedApply"
+   * which by default throws an UnsupportedOperationException.
+   */
+  def apply(parameter: T): R = checkedApply(parameter)
+
+  /**
+   * Override this method if you need to throw checked exceptions
+   *
+   * @throws UnsupportedOperation by default
+   */
+  @throws(classOf[Throwable])
+  def checkedApply(parameter: T): R = throw new UnsupportedOperationException("Mapper.checkedApply has not been implemented")
+}