Allow forcing exception unwrapping even when parent type mappers exist

Author: kevinferrare-1a

docs/src/main/asciidoc/rest.adoc

@@ -2422,6 +2422,32 @@ public class Mapper {
 
 }
 ----
+
+By default, `@UnwrapException` only unwraps exceptions when no exception mapper exists for the wrapper exception or its parent types.
+If you want to force unwrapping even when a parent type mapper exists, use the `always` attribute:
+
+[source,java]
+----
+@UnwrapException(value = {WebApplicationException.class}, always = true)
+public class Mappers {
+
+    @ServerExceptionMapper
+    public Response handleRuntimeException(RuntimeException ex) {
+        // Handles RuntimeException and its subclasses
+        return Response.status(599).build();
+    }
+
+    @ServerExceptionMapper
+    public Response handleJsonProcessingException(JsonProcessingException ex) {
+        // This will be called for JsonProcessingException wrapped in WebApplicationException
+        // because always=true forces unwrapping even though RuntimeException mapper that would match WebApplicationException exists
+        return Response.status(400).entity("Invalid JSON").build();
+    }
+
+}
+----
+
+This is useful when you have a general exception mapper for a parent type (like `RuntimeException`) but want to handle specific wrapped exceptions differently.
 ====
 
 [NOTE]

extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java

@@ -134,6 +134,9 @@ public void applicationSpecificUnwrappedExceptions(CombinedIndexBuildItem combin
         IndexView index = combinedIndexBuildItem.getIndex();
         for (AnnotationInstance instance : index.getAnnotations(UnwrapException.class)) {
             AnnotationValue value = instance.value();
+            AnnotationValue alwaysValue = instance.value("always");
+            boolean always = alwaysValue != null && alwaysValue.asBoolean();
+
             if (value == null) {
                 // in this case we need to use the class where the annotation was placed as the exception to be unwrapped
 
@@ -162,11 +165,11 @@ public void applicationSpecificUnwrappedExceptions(CombinedIndexBuildItem combin
                                     + classInfo.name() + "'.");
                 }
 
-                producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString()));
+                producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString(), always));
             } else {
                 Type[] exceptionTypes = value.asClassArray();
                 for (Type exceptionType : exceptionTypes) {
-                    producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString()));
+                    producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString(), always));
                 }
             }
         }
@@ -186,7 +189,7 @@ public ExceptionMappersBuildItem scanForExceptionMappers(CombinedIndexBuildItem
         exceptions.addBlockingProblem(BlockingOperationNotAllowedException.class);
         exceptions.addBlockingProblem(BlockingNotAllowedException.class);
         for (UnwrappedExceptionBuildItem bi : unwrappedExceptions) {
-            exceptions.addUnwrappedException(bi.getThrowableClassName());
+            exceptions.addUnwrappedException(bi.getThrowableClassName(), bi.isAlways());
         }
         if (capabilities.isPresent(Capability.HIBERNATE_REACTIVE)) {
             exceptions.addNonBlockingProblem(

extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java

@@ -5,17 +5,30 @@
 /**
  * When an {@link Exception} of this type is thrown and no {@code jakarta.ws.rs.ext.ExceptionMapper} exists,
  * then RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * <p>
+ * When {@code always} is {@code true}, unwrapping occurs even if an {@code ExceptionMapper} exists for one
+ * of the class super classes, but not if the exception is directly mapped.
  */
 public final class UnwrappedExceptionBuildItem extends MultiBuildItem {
 
     private final String throwableClassName;
+    private final boolean always;
 
     public UnwrappedExceptionBuildItem(String throwableClassName) {
+        this(throwableClassName, false);
+    }
+
+    public UnwrappedExceptionBuildItem(String throwableClassName, boolean always) {
         this.throwableClassName = throwableClassName;
+        this.always = always;
     }
 
     public UnwrappedExceptionBuildItem(Class<? extends Throwable> throwableClassName) {
-        this.throwableClassName = throwableClassName.getName();
+        this(throwableClassName.getName(), false);
+    }
+
+    public UnwrappedExceptionBuildItem(Class<? extends Throwable> throwableClassName, boolean always) {
+        this(throwableClassName.getName(), always);
     }
 
     @Deprecated(forRemoval = true)
@@ -31,4 +44,8 @@ public Class<? extends Throwable> getThrowableClass() {
     public String getThrowableClassName() {
         return throwableClassName;
     }
+
+    public boolean isAlways() {
+        return always;
+    }
 }

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java

@@ -8,9 +8,32 @@
 /**
  * Used to configure that an exception (or exceptions) should be unwrapped during exception handling.
  * <p>
- * Unwrapping means that when an {@link Exception} of the configured type is thrown and no
- * {@code jakarta.ws.rs.ext.ExceptionMapper} exists,
- * then RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * Unwrapping means that when an {@link Exception} of the configured type is thrown,
+ * RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * <p>
+ * By default ({@code always = false}), unwrapping only occurs when no {@code jakarta.ws.rs.ext.ExceptionMapper}
+ * exists for the exception or its parent types.
+ * <p>
+ * When {@code always = true}, unwrapping occurs even if an {@code ExceptionMapper} exists for one of the exception
+ * parent types, but not if the exception is directly mapped.
+ * <p>
+ * Example:
+ *
+ * <pre>
+ * &#64;UnwrapException(value = { WebApplicationException.class }, always = true)
+ * public class ExceptionsMappers {
+ *     &#64;ServerExceptionMapper
+ *     public RestResponse&lt;Error&gt; mapUnhandledException(RuntimeException ex) {
+ *         // Handles RuntimeException and its subclasses
+ *     }
+ *
+ *     &#64;ServerExceptionMapper
+ *     public RestResponse&lt;Error&gt; mapJsonProcessingException(JsonProcessingException ex) {
+ *         // This will be called for JsonProcessingException wrapped in WebApplicationException
+ *         // because always=true forces unwrapping even though RuntimeException mapper exists
+ *     }
+ * }
+ * </pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
@@ -20,4 +43,12 @@
      * If this is not set, the value is assumed to be the exception class where the annotation is placed
      */
     Class<? extends Exception>[] value() default {};
+
+    /**
+     * When {@code true}, the exception is always unwrapped even if an {@code ExceptionMapper} exists
+     * for the exception or its parent types.
+     * <p>
+     * When {@code false} (default), unwrapping only occurs when no {@code ExceptionMapper} exists.
+     */
+    boolean always() default false;
 }

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/ExceptionMapping.java

@@ -3,10 +3,8 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
@@ -39,7 +37,7 @@ public class ExceptionMapping {
      */
     final List<Predicate<Throwable>> blockingProblemPredicates = new ArrayList<>();
     final List<Predicate<Throwable>> nonBlockingProblemPredicate = new ArrayList<>();
-    final Set<String> unwrappedExceptions = new HashSet<>();
+    final Map<String, Boolean> unwrappedExceptions = new HashMap<>();
 
     public void addBlockingProblem(Class<? extends Throwable> throwable) {
         blockingProblemPredicates.add(new ExceptionTypePredicate(throwable));
@@ -57,11 +55,11 @@ public void addNonBlockingProblem(Predicate<Throwable> predicate) {
         nonBlockingProblemPredicate.add(predicate);
     }
 
-    public void addUnwrappedException(String className) {
-        unwrappedExceptions.add(className);
+    public void addUnwrappedException(String className, boolean always) {
+        unwrappedExceptions.put(className, always);
     }
 
-    public Set<String> getUnwrappedExceptions() {
+    public Map<String, Boolean> getUnwrappedExceptions() {
         return unwrappedExceptions;
     }
 

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/RuntimeExceptionMapper.java

@@ -5,17 +5,18 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
-import java.util.Set;
 import java.util.function.Predicate;
+import java.util.function.Supplier;
 import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import jakarta.ws.rs.WebApplicationException;
 import jakarta.ws.rs.core.Application;
 import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.ext.ExceptionMapper;
 
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.ResteasyReactiveClientProblem;
@@ -35,26 +36,32 @@ public class RuntimeExceptionMapper {
     private static Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwable>> mappers;
 
     /**
-     * Exceptions that indicate an blocking operation was performed on an IO thread.
+     * Exceptions that indicate a blocking operation was performed on an IO thread.
      * <p>
      * We have a special log message for this.
      */
     private final List<Predicate<Throwable>> blockingProblemPredicates;
     private final List<Predicate<Throwable>> nonBlockingProblemPredicate;
-    private final Set<Class<? extends Throwable>> unwrappedExceptions;
+    private final Map<Class<? extends Throwable>, Boolean> unwrappedExceptions;
 
     public RuntimeExceptionMapper(ExceptionMapping mapping, ClassLoader classLoader) {
+        mappers = new HashMap<>();
+        for (var i : mapping.effectiveMappers().entrySet()) {
+            mappers.put(loadThrowableClass(i.getKey(), classLoader), i.getValue());
+        }
+        blockingProblemPredicates = new ArrayList<>(mapping.blockingProblemPredicates);
+        nonBlockingProblemPredicate = new ArrayList<>(mapping.nonBlockingProblemPredicate);
+        unwrappedExceptions = new HashMap<>();
+        for (Map.Entry<String, Boolean> entry : mapping.getUnwrappedExceptions().entrySet()) {
+            Class<? extends Throwable> clazz = loadThrowableClass(entry.getKey(), classLoader);
+            boolean always = entry.getValue();
+            unwrappedExceptions.put(clazz, always);
+        }
+    }
+
+    private static Class<? extends Throwable> loadThrowableClass(String className, ClassLoader classLoader) {
         try {
-            mappers = new HashMap<>();
-            for (var i : mapping.effectiveMappers().entrySet()) {
-                mappers.put((Class<? extends Throwable>) Class.forName(i.getKey(), false, classLoader), i.getValue());
-            }
-            blockingProblemPredicates = new ArrayList<>(mapping.blockingProblemPredicates);
-            nonBlockingProblemPredicate = new ArrayList<>(mapping.nonBlockingProblemPredicate);
-            unwrappedExceptions = new HashSet<>();
-            for (var i : mapping.unwrappedExceptions) {
-                unwrappedExceptions.add((Class<? extends Throwable>) Class.forName(i, false, classLoader));
-            }
+            return (Class<? extends Throwable>) Class.forName(className, false, classLoader);
         } catch (ClassNotFoundException e) {
             throw new RuntimeException("Could not load exception mapper", e);
         }
@@ -226,27 +233,75 @@ private Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwa
         return context.getTarget() != null ? context.getTarget().getClassExceptionMappers() : null;
     }
 
-    @SuppressWarnings({ "unchecked", "rawtypes" })
     private <T extends Throwable> Map.Entry<Throwable, jakarta.ws.rs.ext.ExceptionMapper<? extends Throwable>> doGetExceptionMapper(
             Class<T> clazz,
             Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwable>> mappers,
             Throwable throwable) {
+        if (throwable == null) {
+            return null;
+        }
+        Stream<Supplier<AbstractMap.Entry<Throwable, ExceptionMapper<? extends Throwable>>>> mappingStrategies = Stream.of(
+                // If the exception type is directly mapped, ignore the unwrapping.
+                () -> buildMapperEntryIfExists(clazz, mappers, throwable),
+                // Check if the exception should always be unwrapped (if always=true).
+                // In this case, search mapping for the wrapped exception, ignoring class hierarchy
+                () -> searchMapperForExceptionsToUnwrap(clazz, mappers, throwable, true),
+                // Walk up the class hierarchy looking for a mapper for the type
+                () -> searchMapperInClassHierarchy(clazz, mappers, throwable),
+                // If no mapper found and exception is marked for unwrapping (if always=false), unwrap it
+                () -> searchMapperForExceptionsToUnwrap(clazz, mappers, throwable, false));
+        // Try to get the exception mapper for the exception using strategies in order
+        return mappingStrategies.map(Supplier::get).filter(Objects::nonNull).findFirst().orElse(null);
+    }
+
+    private static AbstractMap.Entry<Throwable, ExceptionMapper<? extends Throwable>> buildMapperEntryIfExists(
+            Class<?> klass,
+            Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwable>> mappers,
+            Throwable throwable) {
+        ResourceExceptionMapper<? extends Throwable> mapper = mappers.get(klass);
+        if (mapper != null) {
+            return new AbstractMap.SimpleEntry<>(
+                    throwable,
+                    mapper.getFactory().createInstance().getInstance());
+        }
+        return null;
+    }
+
+    private <T extends Throwable> Map.Entry<Throwable, ExceptionMapper<? extends Throwable>> searchMapperForExceptionsToUnwrap(
+            Class<T> clazz,
+            Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwable>> mappers,
+            Throwable throwable,
+            boolean alwaysRequestedValue) {
+        if (!unwrappedExceptions.containsKey(clazz)) {
+            // Exception not defined as unwrappable
+            return null;
+        }
+        boolean always = unwrappedExceptions.get(clazz);
+        if (alwaysRequestedValue != always) {
+            // If unwrap is not the requested value ignore the entry
+            return null;
+        }
+        // Do the unwrapping
+        Throwable cause = throwable.getCause();
+        if (cause != null) {
+            return doGetExceptionMapper(cause.getClass(), mappers, cause);
+        }
+        return null;
+    }
+
+    private static <T extends Throwable> AbstractMap.Entry<Throwable, ExceptionMapper<? extends Throwable>> searchMapperInClassHierarchy(
+            Class<T> clazz,
+            Map<Class<? extends Throwable>, ResourceExceptionMapper<? extends Throwable>> mappers,
+            Throwable throwable) {
         Class<?> klass = clazz;
         do {
-            ResourceExceptionMapper<? extends Throwable> mapper = mappers.get(klass);
-            if (mapper != null) {
-                return new AbstractMap.SimpleEntry(throwable, mapper.getFactory()
-                        .createInstance().getInstance());
+            AbstractMap.Entry<Throwable, ExceptionMapper<? extends Throwable>> res = buildMapperEntryIfExists(klass, mappers,
+                    throwable);
+            if (res != null) {
+                return res;
             }
             klass = klass.getSuperclass();
         } while (klass != null);
-
-        if ((throwable != null) && unwrappedExceptions.contains(clazz)) {
-            Throwable cause = throwable.getCause();
-            if (cause != null) {
-                return doGetExceptionMapper(cause.getClass(), mappers, cause);
-            }
-        }
         return null;
     }