Merge master into 14.x

.mvn/extensions.xml

@@ -24,6 +24,6 @@
     <extension>
         <groupId>com.gradle</groupId>
         <artifactId>common-custom-user-data-maven-extension</artifactId>
-        <version>2.3.0</version>
+        <version>2.4.0</version>
     </extension>
 </extensions>

CHANGELOG.md

@@ -8,9 +8,34 @@
 
 ### Version 13.14
 
+* Add `@Experimental` `MultiEncoder`, `PredicatedEncoder` and `EncoderPredicate`, letting a single
+  client route each request to the right encoder. Encoders declare what they can handle by
+  implementing `PredicatedEncoder`; anything else is paired with a predicate via
+  `PredicatedEncoder.of(predicate, encoder)` or `MultiEncoder.builder()`. Encoders are consulted in
+  the order given and a request nothing accepts fails with an `EncodeException` naming what was
+  tried, so a default is an encoder guarded by `EncoderPredicate.any()` listed last. `FormEncoder`
+  and `SpringFormEncoder` gain `createPredicatedFormEncoder()`, a delegate-free flavour that can
+  take part. The first-party JSON encoders (Gson, Jackson, Jackson 3, Jackson Jr, Jackson JAXB,
+  Moshi, Fastjson2, JSON-java) and XML encoders (JAXB, JAXB Jakarta, SOAP, SOAP Jakarta) now declare
+  themselves, and the metrics modules' `MeteredEncoder` forwards `canEncode` to the encoder it
+  wraps. The `Encoder` interface is unchanged, so existing encoders keep working (#3485).
+* Add `@Experimental` `MultiDecoder`, `PredicatedDecoder` and `DecoderPredicate`, the decode-side
+  counterpart, letting a single client route each response to the right decoder. Decoders declare
+  what they can handle by implementing `PredicatedDecoder`; anything else is paired with a predicate
+  via `PredicatedDecoder.of(predicate, decoder)` or `MultiDecoder.builder()`. Decoders are consulted
+  in the order given and a response nothing accepts fails with a `DecodeException` naming what was
+  tried, so a default is a decoder guarded by `DecoderPredicate.any()` listed last. The first-party
+  JSON decoders (Gson, Jackson, Jackson 3, Jackson Jr, Jackson JAXB, Moshi, Fastjson2, JSON-java)
+  and XML decoders (JAXB, JAXB Jakarta, SAX, SOAP, SOAP Jakarta) now declare themselves, and
+  `OptionalDecoder` and the metrics modules' `MeteredDecoder` forward `canDecode` to the decoder
+  they wrap. The `Decoder` interface is unchanged, so existing decoders keep working.
+* `JAXBContextFactory.withProperty` is now applied when creating Unmarshallers, not only
+  Marshallers. Marshaller-only properties are skipped on unmarshal (#3056).
 * Add support for the HTTP QUERY method (RFC 10008) — safe, idempotent, and cacheable with a
   request body. `HttpCacheInterceptor` includes QUERY in its default cacheable set and
   incorporates a body hash into the cache key to reduce cross-body collisions.
+* Flatten `feign-bom` on install/deploy so importing the BOM does not pull `feign-parent`
+  dependency management (for example Jackson) into consumer projects such as Spring Boot.
 
 ### Version 13.12
 

README.md

@@ -663,6 +663,116 @@ public class Example {
 }
 ```
 
+#### Multiple decoders
+
+> This API is `@Experimental` and may change incompatibly, or be removed, in a future release.
+
+A single client sometimes has to read more than one format — JSON for most endpoints, XML for
+a legacy one, plain text for a health check. `MultiDecoder` hands each response to the first decoder
+that accepts it.
+
+Most first-party decoders already declare what they can handle, so they can simply be listed, in the
+order they should be consulted:
+
+```java
+interface MixedClient {
+  @RequestLine("GET /orders/{id}")
+  Order order(@Param("id") String id);
+
+  @RequestLine("GET /legacy/orders/{id}")
+  Order legacyOrder(@Param("id") String id);
+}
+
+public class Example {
+  public static void main(String[] args) {
+    MixedClient client = Feign.builder()
+                              .decoders(new GsonDecoder(), new JAXBDecoder())
+                              .target(MixedClient.class, "https://foo.com");
+  }
+}
+```
+
+Routing is driven by what the server actually sent back, so a client that talks to endpoints
+answering `application/json` and `application/xml` no longer needs one Feign instance per format.
+
+There is no implicit fallback. A response that no decoder accepts fails with a `DecodeException`
+naming the decoders that were tried and what each one wants:
+
+```
+Unable to decode 200 response (Content-Type: text/plain) as com.example.Order. Decoders tried, in order:
+  - GsonDecoder
+  - JAXBDecoder
+Add a decoder guarded by DecoderPredicate.any() last to act as a default.
+```
+
+To get a default, pair a decoder with the predicate that accepts everything and list it **last**:
+
+```java
+Feign.builder()
+     .decoders(
+         new GsonDecoder(),
+         new JAXBDecoder(),
+         PredicatedDecoder.of(DecoderPredicate.any(), new DefaultDecoder()));
+```
+
+The same pairing works for any decoder that does not declare itself, including one you do not
+control. `MultiDecoder.builder()` spells it out when a lambda reads better than a wrapper:
+
+```java
+Decoder decoder =
+    MultiDecoder.builder()
+        .add(new GsonDecoder())                                   // declares itself
+        .add(DecoderPredicate.xmlContentType(), someXmlDecoder)    // paired
+        .add((response, type) -> type == byte[].class, binaryDecoder)
+        .add(DecoderPredicate.any(), new DefaultDecoder())         // the default, last
+        .build();
+```
+
+Decoders are consulted in the order they were added, so put the narrowest one first.
+
+##### Declaring your own decoder
+
+Implement `PredicatedDecoder` and say what you handle. `canDecode` has no default: a decoder that
+declares nothing would claim every response, which is rarely what its author meant.
+
+```java
+public class MyDecoder implements PredicatedDecoder {
+
+  @Override
+  public boolean canDecode(Response response, Type type) {
+    return Util.isJsonContentType(response);
+  }
+
+  @Override
+  public Object decode(Response response, Type type) throws IOException {
+    // ...
+  }
+}
+```
+
+`DecoderPredicate` is the `@FunctionalInterface` here, so predicates can be lambdas. It ships with
+`any()`, `jsonContentType()`, `xmlContentType()`, `contentType(mediaType)`, `emptyBody()`,
+`status(codes...)` and `returnType(type)`, plus `and`/`or`/`negate` to combine them. Each one
+describes itself, which is what shows up in the error message above; wrap your own lambdas in
+`DecoderPredicate.describedAs("it is Tuesday", ...)` to read as well.
+
+`PredicatedDecoder.of(predicate, decoder)` replaces whatever the decoder says about itself, so it
+can widen a decoder as well as narrow it. To keep the decoder's own declaration and add to it, use
+`narrowing`:
+
+```java
+// JSON responses as usual, but only when the call actually succeeded
+PredicatedDecoder.narrowing(DecoderPredicate.status(200, 201), new GsonDecoder());
+```
+
+**Predicates must not read the response body.** For most clients it is a single-pass stream, so
+consuming it in `canDecode` would leave nothing for the decoder that is eventually chosen. Decide
+on the status, the headers and the expected type instead.
+
+**If you wrap a decoder, forward `canDecode` to your delegate**, otherwise wrapping silently changes
+what the decoder handles. `OptionalDecoder` and the metrics modules' `MeteredDecoder` forward for
+exactly this reason.
+
 ### Encoders
 The simplest way to send a request body to a server is to define a `POST` method that has a `String` or `byte[]` parameter without any annotations on it. You will likely need to add a `Content-Type` header.
 
@@ -709,6 +819,131 @@ public class Example {
 }
 ```
 
+#### Multiple encoders
+
+> This API is `@Experimental` and may change incompatibly, or be removed, in a future release.
+
+A single client sometimes has to speak more than one format — JSON for most endpoints, XML for
+a legacy one, plain bytes for an upload. `MultiEncoder` hands each request to the first encoder that
+accepts it.
+
+Most first-party encoders already declare what they can handle, so they can simply be listed, in the
+order they should be consulted:
+
+```java
+interface MixedClient {
+  @RequestLine("POST /orders")
+  @Headers("Content-Type: application/json")
+  void createOrder(Order order);
+
+  @RequestLine("POST /legacy/orders")
+  @Headers("Content-Type: application/xml")
+  void createLegacyOrder(Order order);
+}
+
+public class Example {
+  public static void main(String[] args) {
+    MixedClient client = Feign.builder()
+                              .encoders(new GsonEncoder(), new JAXBEncoder())
+                              .target(MixedClient.class, "https://foo.com");
+  }
+}
+```
+
+There is no implicit fallback. A request that no encoder accepts fails with an `EncodeException`
+naming the encoders that were tried and what each one wants:
+
+```
+Unable to encode java.lang.String (Content-Type: text/plain) for POST /orders. Encoders tried, in order:
+  - GsonEncoder
+  - JAXBEncoder
+Add an encoder guarded by EncoderPredicate.any() last to act as a default.
+```
+
+To get a default, pair an encoder with the predicate that accepts everything and list it **last**:
+
+```java
+Feign.builder()
+     .encoders(
+         new GsonEncoder(),
+         new JAXBEncoder(),
+         PredicatedEncoder.of(EncoderPredicate.any(), new DefaultEncoder()));
+```
+
+The same pairing works for any encoder that does not declare itself, including one you do not
+control. `MultiEncoder.builder()` spells it out when a lambda reads better than a wrapper:
+
+```java
+Encoder encoder =
+    MultiEncoder.builder()
+        .add(new GsonEncoder())                                    // declares itself
+        .add(EncoderPredicate.xmlContentType(), someXmlEncoder)     // paired
+        .add((object, bodyType, template) -> bodyType == byte[].class, binaryEncoder)
+        .add(EncoderPredicate.any(), new DefaultEncoder())          // the default, last
+        .build();
+```
+
+Encoders are consulted in the order they were added, so put the narrowest one first. Note that
+`Content-Type: application/json` with a null body is claimed by a JSON encoder before
+`EncoderPredicate.emptyBody()` gets a chance — order accordingly.
+
+##### Declaring your own encoder
+
+Implement `PredicatedEncoder` and say what you handle. `canEncode` has no default: an encoder that
+declares nothing would claim every request, which is rarely what its author meant.
+
+```java
+public class MyEncoder implements PredicatedEncoder {
+
+  @Override
+  public boolean canEncode(Object object, Type bodyType, RequestTemplate template) {
+    return Util.isJsonContentType(template);
+  }
+
+  @Override
+  public void encode(Object object, Type bodyType, RequestTemplate template) {
+    // ...
+  }
+}
+```
+
+`EncoderPredicate` is the `@FunctionalInterface` here, so predicates can be lambdas. It ships with
+`any()`, `jsonContentType()`, `xmlContentType()`, `contentType(mediaType)`, `emptyBody()`,
+`bodyType(type)` and `formEncoded()`, plus `and`/`or`/`negate` to combine them. Each one describes
+itself, which is what shows up in the error message above; wrap your own lambdas in
+`EncoderPredicate.describedAs("it is Tuesday", ...)` to read as well.
+
+`PredicatedEncoder.of(predicate, encoder)` replaces whatever the encoder says about itself, so it
+can widen an encoder as well as narrow it. To keep the encoder's own declaration and add to it, use
+`narrowing`:
+
+```java
+// only this vendor content type, and only what Gson would have taken anyway
+PredicatedEncoder.narrowing(
+    EncoderPredicate.contentType("application/vnd.acme+json"), new GsonEncoder());
+```
+
+**If you wrap an encoder, forward `canEncode` to your delegate**, otherwise wrapping silently
+changes what the encoder handles. The metrics modules' `MeteredEncoder` forwards for exactly this
+reason.
+
+##### Form encoders
+
+`FormEncoder` and `SpringFormEncoder` wrap a delegate encoder, so they cannot honestly declare what
+they handle — the delegate's applicability is unknown to them. Instead, each offers a
+delegate-free flavour that does:
+
+```java
+Feign.builder()
+     .encoders(
+         FormEncoder.createPredicatedFormEncoder(),  // form and multipart requests only
+         new JacksonEncoder());
+```
+
+It accepts form and multipart requests carrying a map or a user pojo, and leaves everything else to
+the encoders registered alongside it. Constructing one directly with a `null` delegate does the same
+thing: anything it cannot encode itself fails with an `EncodeException` instead of being passed on.
+
 ### @Body templates
 The `@Body` annotation indicates a template to expand using parameters annotated with `@Param`. You will likely need to add a `Content-Type` header.
 

api/src/main/java/feign/BaseBuilder.java

@@ -21,8 +21,14 @@
 import feign.Request.Options;
 import feign.codec.Codec;
 import feign.codec.Decoder;
+import feign.codec.DecoderPredicate;
 import feign.codec.Encoder;
+import feign.codec.EncoderPredicate;
 import feign.codec.ErrorDecoder;
+import feign.codec.MultiDecoder;
+import feign.codec.MultiEncoder;
+import feign.codec.PredicatedDecoder;
+import feign.codec.PredicatedEncoder;
 import feign.interceptor.MethodInterceptor;
 import feign.interceptor.MethodInterceptors;
 import java.lang.reflect.Field;
@@ -98,11 +104,73 @@ public B encoder(Encoder encoder) {
     return thisB();
   }
 
+  /**
+   * Configures a {@link MultiEncoder} built from encoders that declare their own applicability.
+   *
+   * <p>Encoders are consulted in the order given, and the first one that accepts the request
+   * encodes it. There is no implicit fallback: pair an encoder with {@link EncoderPredicate#any()}
+   * and list it last to act as a default, otherwise a request nothing accepts fails with an {@link
+   * feign.codec.EncodeException}.
+   *
+   * <pre>
+   * Feign.builder()
+   *     .encoders(
+   *         new JacksonEncoder(),
+   *         new JAXBEncoder(),
+   *         PredicatedEncoder.of(EncoderPredicate.any(), new DefaultEncoder()))
+   * </pre>
+   *
+   * <p>To pair a predicate with an encoder that does not implement {@link PredicatedEncoder}, use
+   * {@link PredicatedEncoder#of(EncoderPredicate, Encoder)} as above, or {@link
+   * MultiEncoder#builder()} for the same thing spelled out.
+   *
+   * @param encoders the predicated encoders, consulted in the order given
+   */
+  @Experimental
+  public B encoders(PredicatedEncoder... encoders) {
+    MultiEncoder.Builder builder = MultiEncoder.builder();
+    for (PredicatedEncoder encoder : encoders) {
+      builder.add(encoder);
+    }
+    return encoder(builder.build());
+  }
+
   public B decoder(Decoder decoder) {
     this.decoder = decoder;
     return thisB();
   }
 
+  /**
+   * Configures a {@link MultiDecoder} built from decoders that declare their own applicability.
+   *
+   * <p>Decoders are consulted in the order given, and the first one that accepts the response
+   * decodes it. There is no implicit fallback: pair a decoder with {@link DecoderPredicate#any()}
+   * and list it last to act as a default, otherwise a response nothing accepts fails with a {@link
+   * feign.codec.DecodeException}.
+   *
+   * <pre>
+   * Feign.builder()
+   *     .decoders(
+   *         new JacksonDecoder(),
+   *         new JAXBDecoder(),
+   *         PredicatedDecoder.of(DecoderPredicate.any(), new DefaultDecoder()))
+   * </pre>
+   *
+   * <p>To pair a predicate with a decoder that does not implement {@link PredicatedDecoder}, use
+   * {@link PredicatedDecoder#of(DecoderPredicate, Decoder)} as above, or {@link
+   * MultiDecoder#builder()} for the same thing spelled out.
+   *
+   * @param decoders the predicated decoders, consulted in the order given
+   */
+  @Experimental
+  public B decoders(PredicatedDecoder... decoders) {
+    MultiDecoder.Builder builder = MultiDecoder.builder();
+    for (PredicatedDecoder decoder : decoders) {
+      builder.add(decoder);
+    }
+    return decoder(builder.build());
+  }
+
   public B codec(Codec codec) {
     this.encoder = codec.encoder();
     this.decoder = codec.decoder();

api/src/main/java/feign/Contract.java

@@ -60,7 +60,9 @@ public List<MethodMetadata> parseAndValidateMetadata(Class<?> targetType) {
         if (method.getDeclaringClass() == Object.class
             || (method.getModifiers() & Modifier.STATIC) != 0
             || Util.isDefault(method)
-            || method.isAnnotationPresent(FeignIgnore.class)) {
+            || method.isAnnotationPresent(FeignIgnore.class)
+            || method.isSynthetic()
+            || method.isBridge()) {
           continue;
         }
         final MethodMetadata metadata = parseAndValidateMetadata(targetType, method);