#417 add fallback enhancement with whitelistand blacklist

Signed-off-by: Emily Jiang <emijiang6@googlemail.com>

api/src/main/java/org/eclipse/microprofile/faulttolerance/Fallback.java

@@ -36,6 +36,17 @@
  * <li>If fallbackMethod is specified, invoke the method specified by the fallbackMethod on the same class.</li>
  * <li>If both are specified, the {@link org.eclipse.microprofile.faulttolerance.exceptions.FaultToleranceDefinitionException} must be thrown.</li>
  * </ol>
+ * <p>
+ * When a method returns and the Fallback policy is present, the following rules are applied:
+ * <ol>
+ * <li>If the method returns normally (doesn't throw), the result is simply returned.
+ * <li>Otherwise, if the thrown object is assignable to any value in the {@link #skipOn()} parameter, the thrown object will be rethrown.
+ * <li>Otherwise, if the thrown object is assignable to any value in the {@link #applyOn()} parameter, 
+ * the Fallback policy, detailed above, will be applied.
+ * <li>Otherwise the thrown object will be rethrown.
+ * </ol>
+ * If a method throws a {@link Throwable} which is not an {@link Error} or {@link Exception}, non-portable behavior results.
+
  * 
  * @author <a href="mailto:emijiang@uk.ibm.com">Emily Jiang</a>
  * 
@@ -78,4 +89,30 @@ public Void handle(ExecutionContext context) {
     */
     @Nonbinding
     String fallbackMethod() default "";
+
+    /**
+     * The list of exception types which should trigger Fallback
+     * <p>
+     * Note that if a method throws a {@link Throwable} which is not an {@link Error} or {@link Exception}, 
+     * non-portable behavior results.
+     *
+     * @return the exception types which should trigger Fallback
+     */
+    @Nonbinding
+    Class<? extends Throwable>[] applyOn() default {Throwable.class};
+
+    /**
+     * The list of exception types which should not be trigger Fallback
+     * <p>
+     * This list takes priority over the types listed in {@link #applyOn}
+     * <p>
+     * Note that if a method throws a {@link Throwable} which is not an {@link Error} or {@link Exception}, 
+     * non-portable behavior results.
+     *
+     * @return the exception types which should not trigger Fallback
+     */
+    @Nonbinding
+    Class<? extends Throwable>[] skipOn() default {};
+
+
 }

spec/src/main/asciidoc/fallback.asciidoc

@@ -94,5 +94,28 @@ When `fallbackMethod` is used a `FaultToleranceDefinitionException` will be thro
 The parameter `value` and `fallbackMethod` on `@Fallback` cannot be specified at the same time.
 Otherwise, the `FaultToleranceDefinitionException` exception will be thrown.
 
-The fallback should be triggered when an exception occurs.
-For instance, `BulkheadException`, `CircuitBreakerOpenException`, `TimeoutException` should trigger the fallback.
+The fallback might be triggered when an exception occurs (e.g. `BulkheadException`, `CircuitBreakerOpenException`, `TimeoutException`, etc), detailed below.
+When a method returns and the Fallback policy is present, the following rules are applied:
+
+* If the method returns normally (doesn't throw), the result will be simply returned.
+* Otherwise, if the thrown object is assignable to any value in the `skipOn` parameter, the thrown object will be rethrown.
+* Otherwise, if the thrown object is assignable to any value in the `applyOn` parameter, the specified fallback will be triggered.
+* Otherwise the thrown object will be rethrown.
+In the following example, all exceptions assignable to `ExceptionA` and `ExceptionB`, except the ones assignable to `ExceptionBSub` will trigger the fallback operation.
+[source, java]
+----
+
+    @Retry(maxRetries = 2)
+    @Fallback(applyOn={ExceptionA.class, ExceptionB.class}, skipOn=ExceptionBSub.class, fallbackMethod= "fallbackForServiceB")
+    public String serviceB() {
+        counterForInvokingServiceB++;
+       return nameService();
+    }
+
+    private String fallbackForServiceB() {
+        return "myFallback";
+    }
+
+----
+
+If a method throws a `Throwable` which is not an `Error` or `Exception`, non-portable behavior results.