From f743fa450739e586687c8d59bc1629ea086e1489 Mon Sep 17 00:00:00 2001 From: Georgios Andrianakis Date: Wed, 24 Jul 2024 09:53:41 +0300 Subject: [PATCH] Introduce @UnwrapException for Quarkus REST This allows users to configure exceptions whose cause will be checked against exception mappers. This capability already existed in Quarkus REST and was used to map some internal exceptions, but with the new annotation users can opt into the feature for whatever exceptions make sense for their use case. Closes: #42089 --- docs/src/main/asciidoc/rest.adoc | 34 ++++ .../ResteasyReactiveScanningProcessor.java | 53 +++++- .../customexceptions/UnwrapExceptionTest.java | 155 ++++++++++++++++++ .../spi/UnwrappedExceptionBuildItem.java | 24 ++- .../server/ServerExceptionMapper.java | 2 + .../reactive/server/UnwrapException.java | 23 +++ 6 files changed, 284 insertions(+), 7 deletions(-) create mode 100644 extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/customexceptions/UnwrapExceptionTest.java create mode 100644 independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java diff --git a/docs/src/main/asciidoc/rest.adoc b/docs/src/main/asciidoc/rest.adoc index f40b865e34917..7a45e13eac1a9 100644 --- a/docs/src/main/asciidoc/rest.adoc +++ b/docs/src/main/asciidoc/rest.adoc @@ -2271,6 +2271,40 @@ By default, methods annotated with `@ServerExceptionMapper` do **not** run CDI i Users however can opt into interceptors by adding the corresponding annotations to the method. ==== +[TIP] +==== +When mapping an exception to a `@ServerExceptionMapper` method, the cause of the exception normally does not come into play. + +However, some exception types in Java only serve as wrappers for other exceptions. Often, checked exceptions are wrapped into `RuntimeException` just to not have them declared in method `throws` parameters. +Working with `CompletionStage` for example, will require `CompletionException`. There are many such exception types that are just wrappers around the real cause of the exception. + +If you wish to make sure your exception mapper is called for your exception type even when it is wrapped by one of those wrapper exceptions, you can use `@UnwrapException` on the exception wrapper type: + +[source,java] +---- +public class MyExceptionWrapper extends RuntimeException { + public MyExceptionWrapper(Exception cause) { + super(cause); + } +} +---- + +If you don't control that exception wrapper type, you can place the annotation on any class and specify the exception wrapper types it applies to as annotation parameter: + +[source,java] +---- +@UnwrapException({CompletionException.class, RuntimeException.class}) +public class Mapper { + + @ServerExceptionMapper + public Response handleMyException(MyException x) { + // ... + } + +} +---- +==== + [NOTE] ==== Εxception mappers defined in REST endpoint classes will only be called if the exception is thrown in the same class. If you want to define global exception mappers, diff --git a/extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java b/extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java index bd97894704a7f..0f0f08e21ee55 100644 --- a/extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java +++ b/extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java @@ -25,6 +25,7 @@ import org.jboss.jandex.IndexView; import org.jboss.jandex.Indexer; import org.jboss.jandex.MethodInfo; +import org.jboss.jandex.Type; import org.jboss.resteasy.reactive.common.core.BlockingNotAllowedException; import org.jboss.resteasy.reactive.common.model.ResourceContextResolver; import org.jboss.resteasy.reactive.common.model.ResourceExceptionMapper; @@ -33,6 +34,7 @@ import org.jboss.resteasy.reactive.common.processor.ResteasyReactiveDotNames; import org.jboss.resteasy.reactive.common.processor.scanning.ApplicationScanningResult; import org.jboss.resteasy.reactive.common.processor.scanning.ResteasyReactiveInterceptorScanner; +import org.jboss.resteasy.reactive.server.UnwrapException; import org.jboss.resteasy.reactive.server.core.ExceptionMapping; import org.jboss.resteasy.reactive.server.model.ContextResolvers; import org.jboss.resteasy.reactive.server.model.ParamConverterProviders; @@ -82,6 +84,9 @@ */ public class ResteasyReactiveScanningProcessor { + private static final DotName EXCEPTION = DotName.createSimple(Exception.class); + private static final DotName RUNTIME_EXCEPTION = DotName.createSimple(RuntimeException.class); + public static final Set CONDITIONAL_BEAN_ANNOTATIONS; static { @@ -118,11 +123,55 @@ public void accept(ResourceInterceptors interceptors) { } @BuildStep - public List defaultUnwrappedException() { + public List defaultUnwrappedExceptions() { return List.of(new UnwrappedExceptionBuildItem(ArcUndeclaredThrowableException.class), new UnwrappedExceptionBuildItem(RollbackException.class)); } + @BuildStep + public void applicationSpecificUnwrappedExceptions(CombinedIndexBuildItem combinedIndexBuildItem, + BuildProducer producer) { + IndexView index = combinedIndexBuildItem.getIndex(); + for (AnnotationInstance instance : index.getAnnotations(UnwrapException.class)) { + AnnotationValue value = instance.value(); + if (value == null) { + // in this case we need to use the class where the annotation was placed as the exception to be unwrapped + + AnnotationTarget target = instance.target(); + if (target.kind() != AnnotationTarget.Kind.CLASS) { + throw new IllegalStateException( + "@UnwrapException is only supported on classes. Offending target is: " + target); + } + ClassInfo classInfo = target.asClass(); + ClassInfo toCheck = classInfo; + boolean isException = false; + while (true) { + DotName superDotName = toCheck.superName(); + if (EXCEPTION.equals(superDotName) || RUNTIME_EXCEPTION.equals(superDotName)) { + isException = true; + break; + } + toCheck = index.getClassByName(superDotName); + if (toCheck == null) { + break; + } + } + if (!isException) { + throw new IllegalArgumentException( + "Using @UnwrapException without a value is only supported on exception classes. Offending target is '" + + classInfo.name() + "'."); + } + + producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString())); + } else { + Type[] exceptionTypes = value.asClassArray(); + for (Type exceptionType : exceptionTypes) { + producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString())); + } + } + } + } + @BuildStep public ExceptionMappersBuildItem scanForExceptionMappers(CombinedIndexBuildItem combinedIndexBuildItem, ApplicationResultBuildItem applicationResultBuildItem, @@ -137,7 +186,7 @@ public ExceptionMappersBuildItem scanForExceptionMappers(CombinedIndexBuildItem exceptions.addBlockingProblem(BlockingOperationNotAllowedException.class); exceptions.addBlockingProblem(BlockingNotAllowedException.class); for (UnwrappedExceptionBuildItem bi : unwrappedExceptions) { - exceptions.addUnwrappedException(bi.getThrowableClass().getName()); + exceptions.addUnwrappedException(bi.getThrowableClassName()); } if (capabilities.isPresent(Capability.HIBERNATE_REACTIVE)) { exceptions.addNonBlockingProblem( diff --git a/extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/customexceptions/UnwrapExceptionTest.java b/extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/customexceptions/UnwrapExceptionTest.java new file mode 100644 index 0000000000000..c129c8a490d13 --- /dev/null +++ b/extensions/resteasy-reactive/rest/deployment/src/test/java/io/quarkus/resteasy/reactive/server/test/customexceptions/UnwrapExceptionTest.java @@ -0,0 +1,155 @@ +package io.quarkus.resteasy.reactive.server.test.customexceptions; + +import static io.quarkus.resteasy.reactive.server.test.ExceptionUtil.removeStackTrace; +import static io.restassured.RestAssured.when; + +import java.util.function.Supplier; + +import jakarta.ws.rs.Path; +import jakarta.ws.rs.core.Response; + +import org.jboss.resteasy.reactive.server.ServerExceptionMapper; +import org.jboss.resteasy.reactive.server.UnwrapException; +import org.jboss.shrinkwrap.api.ShrinkWrap; +import org.jboss.shrinkwrap.api.spec.JavaArchive; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.RegisterExtension; + +import io.quarkus.resteasy.reactive.server.test.ExceptionUtil; +import io.quarkus.test.QuarkusUnitTest; + +public class UnwrapExceptionTest { + + @RegisterExtension + static QuarkusUnitTest test = new QuarkusUnitTest() + .setArchiveProducer(new Supplier<>() { + @Override + public JavaArchive get() { + return ShrinkWrap.create(JavaArchive.class) + .addClasses(FirstException.class, SecondException.class, ThirdException.class, + FourthException.class, FifthException.class, SixthException.class, + Mappers.class, Resource.class, ExceptionUtil.class); + } + }); + + @Test + public void testWrapperWithUnmappedException() { + when().get("/hello/iaeInSecond") + .then().statusCode(500); + } + + @Test + public void testMappedExceptionWithoutUnwrappedWrapper() { + when().get("/hello/iseInFirst") + .then().statusCode(500); + + when().get("/hello/iseInThird") + .then().statusCode(500); + + when().get("/hello/iseInSixth") + .then().statusCode(500); + } + + @Test + public void testWrapperWithMappedException() { + when().get("/hello/iseInSecond") + .then().statusCode(900); + + when().get("/hello/iseInFourth") + .then().statusCode(900); + + when().get("/hello/iseInFifth") + .then().statusCode(900); + } + + @Path("hello") + public static class Resource { + + @Path("iseInFirst") + public String throwsISEAsCauseOfFirstException() { + throw removeStackTrace(new FirstException(removeStackTrace(new IllegalStateException("dummy")))); + } + + @Path("iseInSecond") + public String throwsISEAsCauseOfSecondException() { + throw removeStackTrace(new SecondException(removeStackTrace(new IllegalStateException("dummy")))); + } + + @Path("iaeInSecond") + public String throwsIAEAsCauseOfSecondException() { + throw removeStackTrace(new SecondException(removeStackTrace(new IllegalArgumentException("dummy")))); + } + + @Path("iseInThird") + public String throwsISEAsCauseOfThirdException() throws ThirdException { + throw removeStackTrace(new ThirdException(removeStackTrace(new IllegalStateException("dummy")))); + } + + @Path("iseInFourth") + public String throwsISEAsCauseOfFourthException() throws FourthException { + throw removeStackTrace(new FourthException(removeStackTrace(new IllegalStateException("dummy")))); + } + + @Path("iseInFifth") + public String throwsISEAsCauseOfFifthException() { + throw removeStackTrace(new FifthException(removeStackTrace(new IllegalStateException("dummy")))); + } + + @Path("iseInSixth") + public String throwsISEAsCauseOfSixthException() { + throw removeStackTrace(new SixthException(removeStackTrace(new IllegalStateException("dummy")))); + } + } + + @UnwrapException({ FourthException.class, FifthException.class }) + public static class Mappers { + + @ServerExceptionMapper + public Response handleIllegalStateException(IllegalStateException e) { + return Response.status(900).build(); + } + } + + public static class FirstException extends RuntimeException { + + public FirstException(Throwable cause) { + super(cause); + } + } + + @UnwrapException + public static class SecondException extends FirstException { + + public SecondException(Throwable cause) { + super(cause); + } + } + + public static class ThirdException extends Exception { + + public ThirdException(Throwable cause) { + super(cause); + } + } + + public static class FourthException extends SecondException { + + public FourthException(Throwable cause) { + super(cause); + } + } + + public static class FifthException extends RuntimeException { + + public FifthException(Throwable cause) { + super(cause); + } + } + + public static class SixthException extends RuntimeException { + + public SixthException(Throwable cause) { + super(cause); + } + } +} diff --git a/extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java b/extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java index 6cb915916c3fa..9bf0b4dbfa59c 100644 --- a/extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java +++ b/extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java @@ -3,18 +3,32 @@ import io.quarkus.builder.item.MultiBuildItem; /** - * When an Exception of this type is thrown and no {@code jakarta.ws.rs.ext.ExceptionMapper} exists, + * 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. */ public final class UnwrappedExceptionBuildItem extends MultiBuildItem { - private final Class throwableClass; + private final String throwableClassName; - public UnwrappedExceptionBuildItem(Class throwableClass) { - this.throwableClass = throwableClass; + public UnwrappedExceptionBuildItem(String throwableClassName) { + this.throwableClassName = throwableClassName; } + public UnwrappedExceptionBuildItem(Class throwableClassName) { + this.throwableClassName = throwableClassName.getName(); + } + + @Deprecated(forRemoval = true) public Class getThrowableClass() { - return throwableClass; + try { + return (Class) Class.forName(throwableClassName, false, + Thread.currentThread().getContextClassLoader()); + } catch (ClassNotFoundException e) { + throw new RuntimeException(e); + } + } + + public String getThrowableClassName() { + return throwableClassName; } } diff --git a/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/ServerExceptionMapper.java b/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/ServerExceptionMapper.java index 7a4689f9ca757..2d0df9e1e8f14 100644 --- a/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/ServerExceptionMapper.java +++ b/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/ServerExceptionMapper.java @@ -41,6 +41,8 @@ *

* The return type of the method must be either be of type {@code Response}, {@code Uni}, {@code RestResponse} or * {@code Uni}. + *

+ * See also {@link UnwrapException} */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) diff --git a/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java b/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java new file mode 100644 index 0000000000000..430757f67ebaa --- /dev/null +++ b/independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java @@ -0,0 +1,23 @@ +package org.jboss.resteasy.reactive.server; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Used to configure that an exception (or exceptions) should be unwrapped during exception handling. + *

+ * 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. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface UnwrapException { + + /** + * If this is not set, the value is assumed to be the exception class where the annotation is placed + */ + Class[] value() default {}; +}