Multi encoder

CHANGELOG.md

@@ -3,6 +3,11 @@
 * `DefaultEncoder` now supports streaming request bodies for `File`, `Path`, `InputStream`, and `Request.Body` types,
   avoiding in-memory buffering. New `Request.PathBody` and `Request.InputStreamBody` implementations are provided for
   these cases. (https://github.com/OpenFeign/feign/pull/3396)
+* `Encoder.encode()` now returns `boolean` — return `true` when encoding succeeds, `false` if
+  the encoder does not handle the type. The `MultiEncoder.of()` factory method composes multiple encoders
+  into a `MultiEncoder` that tries each delegate's `encode()` in order. Existing custom `Encoder` implementations
+  must update the `encode()` return type from `void` to `boolean` and throw EncodeException for true encoding failures.
+  (https://github.com/OpenFeign/feign/pull/3485)
 
 ### Version 13.12
 

MIGRATION-v14.md

@@ -355,6 +355,105 @@ VertxFeign.builder()
 
 ---
 
+### 14. `Encoder.encode()` now returns `boolean` (https://github.com/OpenFeign/feign/pull/3485)
+
+`Encoder.encode()` now returns `boolean` instead of `void`. Return `true` when the encoder
+handles the object, `false` otherwise.
+
+**Before:**
+
+```java
+public class MyEncoder implements Encoder {
+    @Override
+    public void encode(Object object, Type bodyType, RequestTemplate template) {
+        if(bodyType != String.class) throw new EncodeException("Encoding not supported");
+        template.body(Request.Body.of(serialize(object)));
+    }
+}
+```
+
+**After:**
+
+```java
+public class MyEncoder implements Encoder {
+    @Override
+    public boolean encode(Object object, Type bodyType, RequestTemplate template) {
+        template.body(Request.Body.of(serialize(object)));
+        return true; // or return false if the encoder does not handle this type. Do NOT throw EncodeException unless a problem actually happens during encoding.
+    }
+}
+```
+
+Built-in encoders (`DefaultEncoder`, `FormEncoder`, `MeteredEncoder`, `GraphqlEncoder`, etc.) already return `boolean`
+from `encode()`. If your encoder returns `false`, the `MultiEncoder` (see section 19) will try the next encoder. If
+no encoder returns `true`, an `EncodeException` is thrown.
+
+---
+
+### 15. `Encoder` moved from `core` to `api` module
+
+`feign.codec.Encoder` has been relocated from the `feign-core` module to the new `feign-api`
+module. The package name (`feign.codec`) is unchanged. If you have a direct dependency on
+`feign-core` without `feign-api`, you need to add `feign-api` to your classpath.
+
+---
+
+### 16. `Encoder.Default` removed
+
+The deprecated inner class `Encoder.Default` (which extended `DefaultEncoder`) has been removed.
+
+**Before:**
+
+```java
+new Encoder.Default()
+```
+
+**After:**
+
+```java
+new feign.core.codec.DefaultEncoder()
+```
+
+---
+
+### 17. Composing multiple encoders with `MultiEncoder.of()` (https://github.com/OpenFeign/feign/pull/3485)
+
+Use `MultiEncoder.of(...)` to compose multiple encoders into a single `MultiEncoder`, which
+delegates to the first encoder whose `encode()` returns `true`.
+
+**Before:**
+
+```java
+Feign.builder()
+    .encoder(new JacksonEncoder())
+    .target(MyApi.class, "https://api.example.com");
+```
+
+**After (multiple encoders):**
+
+```java
+Feign.builder()
+    .encoder(MultiEncoder.of(
+        new FormEncoder(),
+        new JacksonEncoder(),
+        new JAXBEncoder(factory)
+    ))
+    .target(MyApi.class, "https://api.example.com");
+```
+
+**After (single encoder is unchanged):**
+
+```java
+Feign.builder()
+    .encoder(new JacksonEncoder())
+    .target(MyApi.class, "https://api.example.com");
+```
+
+The `MultiEncoder.of()` factory returns a `MultiEncoder`, which tries
+each encoder's `encode()` and uses the first one that returns `true`.
+
+---
+
 ## Implementing a Custom Streaming Body
 
 If you want to stream a body (e.g., from a file or `InputStream`), implement `Request.Body` directly. Because
@@ -420,6 +519,26 @@ public class FileBody implements Request.Body {
 
 ---
 
+## Selecting Encoder Based on a Predicate
+
+TODO: Once we have specialized EncoderPredicate factory methods (i.e. for xml content types), update this example to use those factory methods
+
+The new `PredicatingEncoder` and `EncoderPredicate` classes can be used in conjunction with `MultiEncoder` to fine tune which Encoder
+handles different types of encode requests.
+
+```java
+Feign.builder()
+    .encoder(MultiEncoder.of(
+    	new DefaultEncoder(),
+    	new PredicatingEncoder((obj, type, templ) -> templ.headers().get("Content-Type").contains("application/xml"), new JAXBEncoder(factory), // handle xml requests
+    	new JacksonEncoder() // handle everything else
+    ))
+    .target(MyApi.class, "https://api.example.com");
+
+```
+
+---
+
 ## Spring Cloud OpenFeign Compatibility
 
 `RequestTemplate#body(byte[], Charset)` is kept `@Deprecated` for backward compatibility with

api/pom.xml

@@ -38,7 +38,7 @@
 
     <dependency>
       <groupId>org.mockito</groupId>
-      <artifactId>mockito-core</artifactId>
+      <artifactId>mockito-junit-jupiter</artifactId>
       <version>${mockito.version}</version>
       <scope>test</scope>
     </dependency>

api/src/main/java/feign/RequestTemplateFactoryResolver.java

@@ -21,6 +21,7 @@
 import feign.codec.EncodeException;
 import feign.codec.Encoder;
 import feign.template.UriUtils;
+import java.lang.reflect.Type;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Iterator;
@@ -232,7 +233,9 @@ protected RequestTemplate resolve(
         }
       }
       try {
-        encoder.encode(formVariables, Encoder.MAP_STRING_WILDCARD, mutable);
+        if (!encoder.encode(formVariables, Encoder.MAP_STRING_WILDCARD, mutable)) {
+          throw new EncodeException("This encoder does not support form encoding: " + encoder);
+        }
       } catch (EncodeException e) {
         throw e;
       } catch (RuntimeException e) {
@@ -269,9 +272,9 @@ protected RequestTemplate resolve(
       try {
         if (alwaysEncodeBody) {
           body = argv == null ? new Object[0] : argv;
-          encoder.encode(body, Object[].class, mutable);
+          encode(body, Object[].class, mutable);
         } else {
-          encoder.encode(body, metadata.bodyType(), mutable);
+          encode(body, metadata.bodyType(), mutable);
         }
       } catch (EncodeException e) {
         throw e;
@@ -280,5 +283,18 @@ protected RequestTemplate resolve(
       }
       return super.resolve(argv, mutable, variables);
     }
+
+    private void encode(Object object, Type bodyType, RequestTemplate mutable)
+        throws EncodeException {
+      if (!encoder.encode(object, bodyType, mutable)) {
+        throw new EncodeException(
+            "This encoder does not support encoding of type: "
+                + bodyType
+                + " with object: "
+                + object
+                + ", encoder: "
+                + encoder);
+      }
+    }
   }
 }

api/src/main/java/feign/Util.java

@@ -371,4 +371,34 @@ public static String getThreadIdentifier() {
         + "_"
         + currentThread.getId();
   }
+
+  /**
+   * Checks if the request template has a content type header that is JSON.
+   *
+   * @param template the request template to check
+   * @return {@code true} if the content type is JSON, {@code false} otherwise
+   * @since 14
+   */
+  public static boolean isJsonContentType(RequestTemplate template) {
+    return template.headers().getOrDefault("Content-Type", List.of()).stream()
+        .anyMatch(
+            contentType ->
+                contentType != null
+                    && contentType.trim().matches("(?i)\\w+/(?:[\\w._-]+\\+)?json.*"));
+  }
+
+  /**
+   * Checks if the request template has a content type header that is XML.
+   *
+   * @param template the request template to check
+   * @return {@code true} if the content type is XML, {@code false} otherwise
+   * @since 14
+   */
+  public static boolean isXmlContentType(RequestTemplate template) {
+    return template.headers().getOrDefault("Content-Type", List.of()).stream()
+        .anyMatch(
+            contentType ->
+                contentType != null
+                    && contentType.trim().matches("(?i)\\w+/(?:[\\w._-]+\\+)?xml.*"));
+  }
 }

api/src/main/java/feign/codec/Encoder.java

@@ -77,7 +77,9 @@ public interface Encoder {
    * @param bodyType the type the object should be encoded as. {@link #MAP_STRING_WILDCARD}
    *     indicates form encoding.
    * @param template the request template to populate.
-   * @throws EncodeException when encoding failed due to a checked exception.
+   * @return {@code true} if the encoder is able to handle the encode request, {@code false} if the
+   *     encoder cannot encode the request
+   * @throws EncodeException if this encoder should be able to encode the request but encoding fails
    */
-  void encode(Object object, Type bodyType, RequestTemplate template) throws EncodeException;
+  boolean encode(Object object, Type bodyType, RequestTemplate template) throws EncodeException;
 }

api/src/main/java/feign/codec/EncoderPredicate.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright © 2012 The Feign Authors (feign@commonhaus.dev)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package feign.codec;
+
+import feign.RequestTemplate;
+import java.lang.reflect.Type;
+
+/** A predicate that determines whether a given object can be encoded by an encoder. */
+@FunctionalInterface
+public interface EncoderPredicate {
+
+  /**
+   * Tests whether the given object can be encoded by an encoder.
+   *
+   * @param object the object to be encoded
+   * @param bodyType the type of the object to be encoded
+   * @param template the request template that will be used to encode the object
+   * @return {@code true} if the object can be encoded, {@code false} otherwise
+   */
+  boolean test(Object object, Type bodyType, RequestTemplate template);
+}

api/src/test/java/feign/RequestTemplateFactoryResolverTest.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright © 2012 The Feign Authors (feign@commonhaus.dev)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package feign;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.params.provider.Arguments.arguments;
+import static org.mockito.Mockito.mock;
+
+import feign.codec.EncodeException;
+import java.util.Map;
+import java.util.function.Supplier;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.FieldSource;
+
+class RequestTemplateFactoryResolverTest {
+  @Nested
+  class BuildFormEncodedTemplateFromArgsTest {
+    @Test
+    void shouldThrowEncodeException() {
+      var methodMetadata = new MethodMetadata();
+      var variables = Map.<String, Object>of("data", "Hello, World!");
+      var factory =
+          new RequestTemplateFactoryResolver.BuildFormEncodedTemplateFromArgs(
+              methodMetadata, mock(), mock(), mock());
+
+      methodMetadata.formParams().add("data");
+
+      assertThrows(
+          EncodeException.class,
+          () -> factory.resolve(new Object[0], new RequestTemplate(), variables));
+    }
+  }
+
+  @Nested
+  class BuildEncodedTemplateFromArgsTest {
+    private static final Supplier<Stream<Arguments>> shouldThrowEncodeException =
+        () -> {
+          var methodMetadata1 = new MethodMetadata();
+          methodMetadata1.alwaysEncodeBody(true);
+
+          var methodMetadata2 = new MethodMetadata();
+          methodMetadata2.bodyIndex(0);
+
+          return Stream.of(
+              arguments(methodMetadata1, new Object[0]),
+              arguments(methodMetadata2, new Object[] {"Hello, World!"}));
+        };
+
+    @ParameterizedTest
+    @FieldSource
+    void shouldThrowEncodeException(MethodMetadata methodMetadata, Object[] argv) {
+      var factory =
+          new RequestTemplateFactoryResolver.BuildEncodedTemplateFromArgs(
+              methodMetadata, mock(), mock(), mock());
+      var mutable = new RequestTemplate();
+
+      mutable.methodMetadata(methodMetadata);
+
+      assertThrows(EncodeException.class, () -> factory.resolve(argv, mutable, Map.of()));
+    }
+  }
+}

core/pom.xml

@@ -85,10 +85,11 @@
 
     <dependency>
       <groupId>org.mockito</groupId>
-      <artifactId>mockito-core</artifactId>
+      <artifactId>mockito-junit-jupiter</artifactId>
       <version>${mockito.version}</version>
       <scope>test</scope>
     </dependency>
+
   </dependencies>
 
   <build>