refactored structure & added javadocs

Author: anjeyy

grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/autoconfigure/GrpcExceptionAdviceAutoConfiguration.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2016-2020 Michael Zhang <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package net.devh.boot.grpc.server.autoconfigure;
+
+import org.springframework.boot.autoconfigure.AutoConfigureAfter;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Conditional;
+import org.springframework.context.annotation.Configuration;
+
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcExceptionHandler;
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcExceptionHandlerMethodResolver;
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcServiceAdvice;
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcServiceAdviceDiscoverer;
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcServiceAdviceExceptionHandler;
+import net.devh.boot.grpc.server.service.exceptionhandling.GrpcServiceAdviceIsPresent;
+
+/**
+ * The auto configuration that will create necessary beans to provide a proper exception handling via annotations
+ * {@link GrpcServiceAdvice @GrpcServiceAdvice} and {@link GrpcExceptionHandler @GrpcExceptionHandler}.
+ * <p>
+ *
+ * @author Andjelko Perisic ([email protected])
+ * @see GrpcServiceAdvice
+ * @see GrpcExceptionHandler
+ */
+@Configuration(proxyBeanMethods = false)
+@EnableConfigurationProperties
+@Conditional(GrpcServiceAdviceIsPresent.class)
+@AutoConfigureAfter(GrpcServerAutoConfiguration.class)
+public class GrpcExceptionAdviceAutoConfiguration {
+
+    @Bean
+    public GrpcServiceAdviceDiscoverer grpcServiceAdviceDiscoverer() {
+        return new GrpcServiceAdviceDiscoverer();
+    }
+
+    @Bean
+    public GrpcExceptionHandlerMethodResolver grpcExceptionHandlerMethodResolver(
+            final GrpcServiceAdviceDiscoverer grpcServiceAdviceDiscoverer) {
+        return new GrpcExceptionHandlerMethodResolver(grpcServiceAdviceDiscoverer);
+    }
+
+    @Bean
+    public GrpcServiceAdviceExceptionHandler grpcServiceAdviceExceptionHandler(
+            GrpcExceptionHandlerMethodResolver grpcExceptionHandlerMethodResolver) {
+        return new GrpcServiceAdviceExceptionHandler(grpcExceptionHandlerMethodResolver);
+    }
+
+}

grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/service/exceptionhandling/GrpcExceptionHandler.java

@@ -24,18 +24,60 @@
 import java.lang.annotation.Target;
 
 /**
- * TODO..
+ * Methods annotated with {@link GrpcExceptionHandler @GrpcExceptionHandler} are being mapped to a corresponding
+ * Exception, by declaring either in {@link GrpcExceptionHandler#value() @GrpcExceptionHandler(value = ...)} as value or
+ * as annotated methods parameter (both is working too).
+ * <p>
+ * Return type of annotated methods has to be of type {@link Throwable} or {@link io.grpc.Status}, the latter is wrapped
+ * up later as {@link io.grpc.StatusRuntimeException}. For more detailed information
+ * {@link GrpcExceptionHandlerMethodResolver}. <br>
+ * <p>
+ *
+ * As an example, this is the preferred way of handling exception,
+ * 
+ * <pre>
+ * {@code @GrpcExceptionHandler
+ *    public Status handleIllegalArgumentException(IllegalArgumentException e){
+ *      return Status.INVALID_ARGUMENT
+ *                   .withDescription(e.getMessage())
+ *                   .withCause(e);
+ *    }
+ *  }
+ * </pre>
+ * 
+ * but the following is also possible, especially if {@link io.grpc.Metadata} has to be returned.
+ * 
+ * <pre>
+ * {@code @GrpcExceptionHandler
+ *    public StatusRuntimeException handleIllegalArgumentException(IllegalArgumentException e){
+ *      Status status = Status.INVALID_ARGUMENT
+ *                            .withDescription(e.getMessage())
+ *                            .withCause(e);
+ *      return status.asRuntimeException();
+ *    }
+ *  }
+ * </pre>
+ * 
+ * Further when an {@link Exception} is raised by the application during runtime,
+ * {@link GrpcServiceAdviceExceptionHandler} interrupts after thrown exception and executes above mentioned annotated
+ * method which was mapped by {@link GrpcExceptionHandler @GrpcExceptionHandler} inside a class annotated with
+ * {@link GrpcServiceAdvice @GrpcServiceAdvice}.<br>
+ * <p>
  * 
- * @author Andjelko ([email protected])
+ * @author Andjelko Perisic ([email protected])
+ * @see GrpcServiceAdvice
+ * @see GrpcExceptionHandlerMethodResolver
+ * @see GrpcServiceAdviceExceptionHandler
  */
 @Documented
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface GrpcExceptionHandler {
 
     /**
-     * Exceptions handled by the annotated method. If empty, will default to any exceptions listed in the method
-     * argument list.
+     * Exceptions handled by the annotated method.
+     * 
+     * If empty, will default to any exceptions listed in the method argument list.
      */
     Class<? extends Throwable>[] value() default {};
 }

grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/service/exceptionhandling/GrpcExceptionHandlerMethodResolver.java

@@ -22,66 +22,44 @@
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.Map;
-import java.util.Set;
-import java.util.function.Function;
-import java.util.stream.Collectors;
-import java.util.stream.Stream;
 
 import org.springframework.beans.factory.InitializingBean;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
-import org.springframework.context.ApplicationContext;
-import org.springframework.stereotype.Component;
 import org.springframework.util.Assert;
 
 import lombok.extern.slf4j.Slf4j;
 
 /**
- * TODO..
+ * Given an annotated {@link GrpcServiceAdvice @GrpcServiceAdvice} class and annotated methods with
+ * {@link GrpcExceptionHandler @GrpcExceptionHandler}, {@link GrpcExceptionHandlerMethodResolver} resolves given
+ * exception type and maps it to the corresponding method to be executed, when this exception is being raised.<br>
+ * For an example how to make use of it, please have a look {@link GrpcExceptionHandler @GrpcExceptionHandler}.<br>
+ * <br>
  * 
- * @author Andjelko ([email protected])
+ * @author Andjelko Perisic ([email protected])
+ * @see GrpcServiceAdvice
+ * @see GrpcExceptionHandler
+ * @see GrpcServiceAdviceExceptionHandler
  */
 @Slf4j
-@Component
-@ConditionalOnBean(annotation = GrpcServiceAdvice.class)
-class GrpcExceptionHandlerMethodResolver implements InitializingBean {
+public class GrpcExceptionHandlerMethodResolver implements InitializingBean {
 
     private final Map<Class<? extends Throwable>, Method> mappedMethods = new HashMap<>(16);
-    private final ApplicationContext applicationContext;
 
-    private Class<? extends Throwable>[] annotatedExceptions;
-    private Map<String, Object> annotatedBeans;
+    private final GrpcServiceAdviceDiscoverer grpcServiceAdviceDiscoverer;
 
+    private Class<? extends Throwable>[] annotatedExceptions;
 
-    GrpcExceptionHandlerMethodResolver(final ApplicationContext applicationContext) {
-        this.applicationContext = applicationContext;
+    public GrpcExceptionHandlerMethodResolver(final GrpcServiceAdviceDiscoverer grpcServiceAdviceDiscoverer) {
+        this.grpcServiceAdviceDiscoverer = grpcServiceAdviceDiscoverer;
     }
 
     @Override
     public void afterPropertiesSet() throws Exception {
-        Set<Class<?>> annotatedClasses = findAllAnnotatedClasses();
-        Set<Method> annotatedMethods = getAnnotatedMethods(annotatedClasses);
-
-        annotatedMethods.forEach(this::checkParamTypesAreAlignedToExceptionTypes);
-    }
-
-    private Set<Class<?>> findAllAnnotatedClasses() {
-        annotatedBeans = applicationContext.getBeansWithAnnotation(GrpcServiceAdvice.class);
-        return annotatedBeans.values()
-                .stream()
-                .map(Object::getClass)
-                .collect(Collectors.toSet());
-    }
-
-    private Set<Method> getAnnotatedMethods(Set<Class<?>> annotatedClasses) {
-        Function<Class<?>, Stream<Method>> extractMethodsFromClass = clazz -> Arrays.stream(clazz.getDeclaredMethods());
-        return annotatedClasses.stream()
-                .flatMap(extractMethodsFromClass)
-                .filter(method -> method.isAnnotationPresent(GrpcExceptionHandler.class))
-                .collect(Collectors.toSet());
+        grpcServiceAdviceDiscoverer.getAnnotatedMethods()
+                .forEach(this::extractAndMapExceptionToMethod);
     }
 
-
-    private void checkParamTypesAreAlignedToExceptionTypes(Method method) {
+    private void extractAndMapExceptionToMethod(Method method) {
 
         GrpcExceptionHandler annotation = method.getDeclaredAnnotation(GrpcExceptionHandler.class);
         Assert.notNull(annotation, "@GrpcExceptionHandler annotation not found.");
@@ -107,6 +85,17 @@ private Class<? extends Throwable>[] checkForExceptionType(Class<?>[] methodPara
         return paramExceptionTypes;
     }
 
+    private void addExceptionMapping(Class<? extends Throwable> exceptionType, Method method) {
+
+        parameterTypeIsAssignable(exceptionType);
+
+        Method oldMethod = mappedMethods.put(exceptionType, method);
+        if (oldMethod != null && !oldMethod.equals(method)) {
+            throw new IllegalStateException("Ambiguous @GrpcExceptionHandler method mapped for [" +
+                    exceptionType + "]: {" + oldMethod + ", " + method + "}");
+        }
+    }
+
     private void parameterTypeIsAssignable(Class<? extends Throwable> paramType) {
 
         if (annotatedExceptions.length == 0) {
@@ -123,17 +112,6 @@ private void parameterTypeIsAssignable(Class<? extends Throwable> paramType) {
                         paramType, Arrays.toString(annotatedExceptions)));
     }
 
-    private void addExceptionMapping(Class<? extends Throwable> exceptionType, Method method) {
-
-        parameterTypeIsAssignable(exceptionType);
-
-        Method oldMethod = mappedMethods.put(exceptionType, method);
-        if (oldMethod != null && !oldMethod.equals(method)) {
-            throw new IllegalStateException("Ambiguous @GrpcExceptionHandler method mapped for [" +
-                    exceptionType + "]: {" + oldMethod + ", " + method + "}");
-        }
-    }
-
 
     public <E extends Throwable> Map.Entry<Object, Method> resolveMethodWithInstance(Class<E> exceptionType) {
 
@@ -143,7 +121,8 @@ public <E extends Throwable> Map.Entry<Object, Method> resolveMethodWithInstance
         }
 
         Class<?> methodClass = value.getDeclaringClass();
-        Object key = annotatedBeans.values()
+        Object key = grpcServiceAdviceDiscoverer.getAnnotatedBeans()
+                .values()
                 .stream()
                 .filter(obj -> methodClass.isAssignableFrom(obj.getClass()))
                 .findFirst()
@@ -163,5 +142,4 @@ private <E extends Throwable> Method extractExtendedThrowable(Class<E> exception
                 .orElse(null);
     }
 
-
 }

grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/service/exceptionhandling/GrpcServiceAdvice.java

@@ -26,9 +26,14 @@
 import org.springframework.stereotype.Component;
 
 /**
- * Special {@link Component @Component} to declare GrpcException Handling.
+ * Special {@link Component @Component} to declare {@link GrpcExceptionHandler GrpcException Handling}.
  * 
- * @author Andjelko ([email protected])
+ * Every class annotated with {@link GrpcServiceAdvice @GrpcServiceAdvice} is marked to be scanned for
+ * {@link GrpcExceptionHandler @GrpcExceptionHandler} annotations.
+ * 
+ * @author Andjelko Perisic ([email protected])
+ * 
+ * @see GrpcExceptionHandler
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

grpc-server-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/server/service/exceptionhandling/GrpcServiceAdviceDiscoverer.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2016-2020 Michael Zhang <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package net.devh.boot.grpc.server.service.exceptionhandling;
+
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * A discovery class to find all Beans annotated with {@link GrpcServiceAdvice @GrpcServiceAdvice} and for all found
+ * beans a second search is performed looking for methods with {@link GrpcExceptionHandler @GrpcExceptionHandler}.<br>
+ * <br>
+ * 
+ * @author Andjelko Perisic ([email protected])
+ * @see GrpcServiceAdvice
+ * @see GrpcExceptionHandler
+ */
+@Slf4j
+public class GrpcServiceAdviceDiscoverer implements InitializingBean, ApplicationContextAware {
+
+    private ApplicationContext applicationContext;
+    private Map<String, Object> annotatedBeans;
+    private Set<Class<?>> annotatedClasses;
+    private Set<Method> annotatedMethods;
+
+
+    Map<String, Object> getAnnotatedBeans() {
+        return annotatedBeans;
+    }
+
+    Set<Method> getAnnotatedMethods() {
+        return annotatedMethods;
+    }
+
+
+    @Override
+    public void afterPropertiesSet() throws Exception {
+
+        annotatedBeans = applicationContext.getBeansWithAnnotation(GrpcServiceAdvice.class);
+        annotatedClasses = findAllAnnotatedClasses();
+        annotatedMethods = getAnnotatedMethods(annotatedClasses);
+    }
+
+    private Set<Class<?>> findAllAnnotatedClasses() {
+        return annotatedBeans.values()
+                .stream()
+                .map(Object::getClass)
+                .collect(Collectors.toSet());
+    }
+
+    private Set<Method> getAnnotatedMethods(Set<Class<?>> annotatedClasses) {
+        Function<Class<?>, Stream<Method>> extractMethodsFromClass = clazz -> Arrays.stream(clazz.getDeclaredMethods());
+        return annotatedClasses.stream()
+                .flatMap(extractMethodsFromClass)
+                .filter(method -> method.isAnnotationPresent(GrpcExceptionHandler.class))
+                .collect(Collectors.toSet());
+    }
+
+    boolean isAnnotationPresent() {
+
+        return !annotatedClasses.isEmpty() && !annotatedMethods.isEmpty();
+    }
+
+    @Override
+    public void setApplicationContext(final ApplicationContext applicationContext) {
+        this.applicationContext = applicationContext;
+    }
+}