Merge pull request #2 from saintf/master

Initial commit of Feign annotation error decoder

Author: saintf

.gitignore

@@ -1,12 +1,3 @@
-*.class
-
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
-
-# Package Files #
-*.jar
-*.war
-*.ear
-
-# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
-hs_err_pid*
+.idea
+target
+*.iml

README.md

@@ -0,0 +1,141 @@
+Annotation Error Decoder
+=========================
+
+This module allows to annotate Feign's interfaces with annotations to generate Exceptions based on error codes
+
+To use AnnotationErrorDecoder with Feign, add the Annotation Error Decoder module to your classpath. Then, configure
+Feign to use the AnnotationErrorDecoder:
+
+```java
+GitHub github = Feign.builder()
+                     .errorDecoder(
+                         AnnotationErrorDecoder.builderFor(GitHub.class).build()
+                     )
+                     .target(GitHub.class, "https://api.github.com");
+```
+
+## Leveraging the annotations and priority order
+For annotation decoding to work, the class must be annotated with `@ErrorHandling` tags.
+The tags are valid in both the class level as well as method level. They will be treated from 'most specific' to 
+'least specific' in the following order:
+* A code specific exception defined on the method 
+* A code specific exception defined on the class
+* The default exception of the method
+* The default exception of the class
+
+```java
+@ErrorHandling(codeSpecific =
+    {
+        @ErrorCodes( codes = {401}, generate = UnAuthorizedException.class),
+        @ErrorCodes( codes = {403}, generate = ForbiddenException.class),
+        @ErrorCodes( codes = {404}, generate = UnknownItemException.class),
+    },
+    defaultException = ClassLevelDefaultException.class
+)
+interface GitHub {
+
+    @ErrorHandling(codeSpecific =
+        {
+            @ErrorCodes( codes = {404}, generate = NonExistentRepoException.class),
+            @ErrorCodes( codes = {502, 503, 504}, generate = RetryAfterCertainTimeException.class),
+        },
+        defaultException = FailedToGetContributorsException.class
+    )
+    @RequestLine("GET /repos/{owner}/{repo}/contributors")
+    List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo);
+}
+```
+In the above example, error responses to 'contributors' would hence be mapped as follows by status codes:
+
+| Code        | Exception                          | Reason                |
+| ----------- | --------------------------------   | --------------------- |
+| 401         | `UnAuthorizedException`            | from Class definition |
+| 403         | `ForbiddenException`               | from Class definition |
+| 404         | `NonExistenRepoException`          | from Method definition, note that the class generic exception won't be thrown here |
+| 502,503,504 | `RetryAfterCertainTimeException`   | from method definition. Note that you can have multiple error codes generate the same type of exception |
+| Any Other   | `FailedToGetContributorsException` | from Method default   |
+
+For a class level default exception to be thrown, the method must not have a `defaultException` defined, nor must the error code
+be mapped at either the method or class level.
+
+If the return code cannot be mapped to any code and no default exceptions have been configured, then the decoder will
+drop to a default decoder (by default, the standard one provided by feign). You can change the default drop-into decoder
+as follows:
+
+```java
+GitHub github = Feign.builder()
+                     .errorDecoder(
+                         AnnotationErrorDecoder.builderFor(GitHub.class)
+                            .withDefaultDecoder(new MyOtherErrorDecoder())
+                            .build()
+                     )
+                     .target(GitHub.class, "https://api.github.com");
+```
+
+ 
+## Complex Exceptions
+
+Finally, Any exception can be used if they have a default constructor:
+
+```java
+class DefaultConstructorException extends Exception {}
+```
+
+However, if you want to have parameters (such  as the body in the error response or headers), you have to annotate its 
+constructor appropriately (the body annotation is optional, provided there aren't paramters which will clash)
+
+All the following examples are valid exceptions:
+```java
+class JustBody extends Exception {
+
+    @FeignExceptionConstructor
+    public JustBody(String body) {
+
+    }
+}
+//Headers must be of type Map<String, Collection<String>>
+class BodyAndHeaders extends Exception {
+
+    @FeignExceptionConstructor
+    public BodyAndHeaders(@ResponseBody String body, @ResponseHeaders Map<String, Collection<String>> headers) {
+
+    }
+}
+class JustHeaders extends Exception {
+
+    @FeignExceptionConstructor
+    public JustHeaders(@ResponseHeaders Map<String, Collection<String>> headers) {
+
+    }
+}
+```
+
+If you want to have the body decoded, you'll need to pass a decoder at construction time (just as for normal responses):
+
+```java
+GitHub github = Feign.builder()
+                     .errorDecoder(
+                         AnnotationErrorDecoder.builderFor(GitHub.class)
+                            .withResponseBodyDecoder(new JacksonDecoder())
+                            .build()
+                     )
+                     .target(GitHub.class, "https://api.github.com");
+```
+
+This will enable you to create exceptions where the body is a complex pojo:
+
+```java
+class ComplexPojoException extends Exception {
+
+    @FeignExceptionConstructor
+    public ComplexPojoException(GithubExceptionResponse body) {
+
+    }
+}
+//The pojo can then be anything you'd like provided the decoder can manage it
+class GithubExceptionResponse {
+    public String message;
+    public int githubCode;
+    public List<String> urlsForHelp;
+}
+```

pom.xml

@@ -0,0 +1,36 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.github.openfeign</groupId>
+        <artifactId>parent</artifactId>
+        <version>9.5.0</version>
+    </parent>
+
+    <artifactId>feign-annotation-error-decoder</artifactId>
+    <version>0.1.0</version>
+    <name>Feign Annotation Error Decoder</name>
+    <description>Feign Annotation Error Decoder</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>feign-core</artifactId>
+            <version>${project.parent.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>feign-core</artifactId>
+            <version>${project.parent.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>com.squareup.okhttp3</groupId>
+            <artifactId>mockwebserver</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

src/main/java/feign/error/AnnotationErrorDecoder.java

@@ -0,0 +1,132 @@
+package feign.error;
+
+import feign.Response;
+import feign.codec.Decoder;
+import feign.codec.ErrorDecoder;
+
+import java.lang.reflect.Method;
+import java.util.HashMap;
+import java.util.Map;
+
+import static feign.Feign.configKey;
+
+public class AnnotationErrorDecoder implements ErrorDecoder {
+
+    private final Map<String, MethodErrorHandler> errorHandlerMap;
+    private final ErrorDecoder defaultDecoder;
+
+
+    AnnotationErrorDecoder(Map<String, MethodErrorHandler> errorHandlerMap, ErrorDecoder defaultDecoder) {
+        this.errorHandlerMap = errorHandlerMap;
+        this.defaultDecoder = defaultDecoder;
+    }
+
+    @Override
+    public Exception decode(String methodKey, Response response) {
+        if(errorHandlerMap.containsKey(methodKey)) {
+            return errorHandlerMap.get(methodKey).decode(response);
+        }
+        return defaultDecoder.decode(methodKey, response);
+    }
+
+
+    public static AnnotationErrorDecoder.Builder builderFor(Class<?> apiType) {
+        return new Builder(apiType);
+    }
+
+    public static class Builder {
+        private final Class<?> apiType;
+        private ErrorDecoder defaultDecoder = new ErrorDecoder.Default();
+        private Decoder responseBodyDecoder = new Decoder.Default();
+
+
+        public Builder(Class<?> apiType) {
+            this.apiType = apiType;
+        }
+
+        public Builder withDefaultDecoder(ErrorDecoder defaultDecoder) {
+            this.defaultDecoder = defaultDecoder;
+            return this;
+        }
+
+        public Builder withResponseBodyDecoder(Decoder responseBodyDecoder) {
+            this.responseBodyDecoder = responseBodyDecoder;
+            return this;
+        }
+
+        public AnnotationErrorDecoder build() {
+            Map<String, MethodErrorHandler> errorHandlerMap = generateErrorHandlerMapFromApi(apiType);
+            return new AnnotationErrorDecoder(errorHandlerMap, defaultDecoder);
+        }
+
+        Map<String, MethodErrorHandler> generateErrorHandlerMapFromApi(Class<?> apiType) {
+
+            ExceptionGenerator classLevelDefault = new ExceptionGenerator.Builder()
+                .withResponseBodyDecoder(responseBodyDecoder)
+                .withExceptionType(ErrorHandling.NO_DEFAULT.class)
+                .build();
+            Map<Integer, ExceptionGenerator> classLevelStatusCodeDefinitions = new HashMap<Integer, ExceptionGenerator>();
+
+            if(apiType.isAnnotationPresent(ErrorHandling.class)) {
+                ErrorHandlingDefinition classErrorHandlingDefinition = readAnnotation(apiType.getAnnotation(ErrorHandling.class), responseBodyDecoder);
+                classLevelDefault = classErrorHandlingDefinition.defaultThrow;
+                classLevelStatusCodeDefinitions = classErrorHandlingDefinition.statusCodesMap;
+            }
+
+            Map<String, MethodErrorHandler> methodErrorHandlerMap = new HashMap<String, MethodErrorHandler>();
+            for(Method method : apiType.getMethods()) {
+                if(method.isAnnotationPresent(ErrorHandling.class)) {
+                    ErrorHandlingDefinition methodErrorHandling = readAnnotation(method.getAnnotation(ErrorHandling.class), responseBodyDecoder);
+                    ExceptionGenerator methodDefault = methodErrorHandling.defaultThrow;
+                    if(methodDefault.getExceptionType().equals(ErrorHandling.NO_DEFAULT.class)) {
+                        methodDefault = classLevelDefault;
+                    }
+
+                    MethodErrorHandler methodErrorHandler =
+                        new MethodErrorHandler(methodErrorHandling.statusCodesMap, classLevelStatusCodeDefinitions, methodDefault );
+
+                    methodErrorHandlerMap.put(configKey(apiType, method), methodErrorHandler);
+                }
+            }
+
+            return methodErrorHandlerMap;
+        }
+
+        static ErrorHandlingDefinition readAnnotation(ErrorHandling errorHandling, Decoder responseBodyDecoder) {
+            ExceptionGenerator defaultException = new ExceptionGenerator.Builder()
+                .withResponseBodyDecoder(responseBodyDecoder)
+                .withExceptionType(errorHandling.defaultException())
+                .build();
+            Map<Integer, ExceptionGenerator> statusCodesDefinition = new HashMap<Integer, ExceptionGenerator>();
+
+            for(ErrorCodes statusCodeDefinition : errorHandling.codeSpecific()) {
+                for(int statusCode : statusCodeDefinition.codes()) {
+                    if(statusCodesDefinition.containsKey(statusCode)) {
+                        throw new IllegalStateException(
+                            "Status Code [" + statusCode + "] " +
+                                "has already been declared to throw [" + statusCodesDefinition.get(statusCode).getExceptionType().getName() + "] " +
+                                "and [" + statusCodeDefinition.generate() + "] - dupe definition");
+                    }
+                    statusCodesDefinition.put(statusCode,
+                        new ExceptionGenerator.Builder()
+                            .withResponseBodyDecoder(responseBodyDecoder)
+                            .withExceptionType(statusCodeDefinition.generate())
+                            .build());
+                }
+            }
+
+            return new ErrorHandlingDefinition(defaultException, statusCodesDefinition);
+        }
+
+        private static class ErrorHandlingDefinition {
+            private final ExceptionGenerator defaultThrow;
+            private final Map<Integer, ExceptionGenerator> statusCodesMap;
+
+
+            private ErrorHandlingDefinition(ExceptionGenerator defaultThrow, Map<Integer, ExceptionGenerator> statusCodesMap) {
+                this.defaultThrow = defaultThrow;
+                this.statusCodesMap = statusCodesMap;
+            }
+        }
+    }
+}

src/main/java/feign/error/ErrorCodes.java

@@ -0,0 +1,6 @@
+package feign.error;
+
+public @interface ErrorCodes {
+    int[] codes();
+    Class<? extends Exception> generate();
+}

src/main/java/feign/error/ErrorHandling.java

@@ -0,0 +1,15 @@
+package feign.error;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface ErrorHandling {
+    ErrorCodes[] codeSpecific() default {};
+    Class<? extends Exception> defaultException() default NO_DEFAULT.class;
+
+    final class NO_DEFAULT extends Exception {}
+}