}.
+ * Note on exception propagation
Exceptions thrown by {@link Decoder}s get wrapped in a
+ * {@link DecodeException} unless they are a subclass of {@link FeignException} already, and unless
+ * the client was configured with {@link Feign.Builder#decode404()}.
+ */
+public interface Decoder {
+
+ /**
+ * Decodes an http response into an object corresponding to its
+ * {@link java.lang.reflect.Method#getGenericReturnType() generic return type}. If you need to
+ * wrap exceptions, please do so via {@link DecodeException}.
+ *
+ * @param response the response to decode
+ * @param type {@link java.lang.reflect.Method#getGenericReturnType() generic return type} of the
+ * method corresponding to this {@code response}.
+ * @return instance of {@code type}
+ * @throws IOException will be propagated safely to the caller.
+ * @throws DecodeException when decoding failed due to a checked exception besides IOException.
+ * @throws FeignException when decoding succeeds, but conveys the operation failed.
+ */
+ Object decode(Response response, Type type) throws IOException, DecodeException, FeignException;
+
+ /** Default implementation of {@code Decoder}. */
+ public class Default extends StringDecoder {
+
+ @Override
+ public Object decode(Response response, Type type) throws IOException {
+ if (response.status() == 404 || response.status() == 204)
+ return Util.emptyValueOf(type);
+ if (response.body() == null)
+ return null;
+ if (byte[].class.equals(type)) {
+ return Util.toByteArray(response.body().asInputStream());
+ }
+ return super.decode(response, type);
+ }
+ }
+}
diff --git a/core/src/main/java/feign/codec/EncodeException.java b/core/src/main/java/feign/codec/EncodeException.java
new file mode 100644
index 000000000..57c586881
--- /dev/null
+++ b/core/src/main/java/feign/codec/EncodeException.java
@@ -0,0 +1,42 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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 static feign.Util.checkNotNull;
+import feign.FeignException;
+
+/**
+ * Similar to {@code javax.websocket.EncodeException}, raised when a problem occurs encoding a
+ * message. Note that {@code EncodeException} is not an {@code IOException}, nor does it have one
+ * set as its cause.
+ */
+public class EncodeException extends FeignException {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * @param message the reason for the failure.
+ */
+ public EncodeException(String message) {
+ super(-1, checkNotNull(message, "message"));
+ }
+
+ /**
+ * @param message possibly null reason for the failure.
+ * @param cause the cause of the error.
+ */
+ public EncodeException(String message, Throwable cause) {
+ super(-1, message, checkNotNull(cause, "cause"));
+ }
+}
diff --git a/core/src/main/java/feign/codec/Encoder.java b/core/src/main/java/feign/codec/Encoder.java
new file mode 100644
index 000000000..dc4f0164d
--- /dev/null
+++ b/core/src/main/java/feign/codec/Encoder.java
@@ -0,0 +1,98 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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 java.lang.reflect.Type;
+import feign.RequestTemplate;
+import feign.Util;
+import static java.lang.String.format;
+
+/**
+ * Encodes an object into an HTTP request body. Like {@code javax.websocket.Encoder}. {@code
+ * Encoder} is used when a method parameter has no {@code @Param} annotation. For example:
+ *
+ *
+ *
+ * @POST
+ * @Path("/")
+ * void create(User user);
+ *
+ *
+ * Example implementation:
+ *
+ *
+ *
+ * public class GsonEncoder implements Encoder {
+ * private final Gson gson;
+ *
+ * public GsonEncoder(Gson gson) {
+ * this.gson = gson;
+ * }
+ *
+ * @Override
+ * public void encode(Object object, Type bodyType, RequestTemplate template) {
+ * template.body(gson.toJson(object, bodyType));
+ * }
+ * }
+ *
+ *
+ *
+ *
Form encoding
+ *
+ * If any parameters are found in {@link feign.MethodMetadata#formParams()}, they will be collected
+ * and passed to the Encoder as a map.
+ *
+ *
+ * Ex. The following is a form. Notice the parameters aren't consumed in the request line. A map
+ * including "username" and "password" keys will passed to the encoder, and the body type will be
+ * {@link #MAP_STRING_WILDCARD}.
+ *
+ *
+ * @RequestLine("POST /")
+ * Session login(@Param("username") String username, @Param("password") String password);
+ *
+ */
+public interface Encoder {
+ /** Type literal for {@code Map}, indicating the object to encode is a form. */
+ Type MAP_STRING_WILDCARD = Util.MAP_STRING_WILDCARD;
+
+ /**
+ * Converts objects to an appropriate representation in the template.
+ *
+ * @param object what to encode as the request body.
+ * @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.
+ */
+ void encode(Object object, Type bodyType, RequestTemplate template) throws EncodeException;
+
+ /**
+ * Default implementation of {@code Encoder}.
+ */
+ class Default implements Encoder {
+
+ @Override
+ public void encode(Object object, Type bodyType, RequestTemplate template) {
+ if (bodyType == String.class) {
+ template.body(object.toString());
+ } else if (bodyType == byte[].class) {
+ template.body((byte[]) object, null);
+ } else if (object != null) {
+ throw new EncodeException(
+ format("%s is not a type supported by this encoder.", object.getClass()));
+ }
+ }
+ }
+}
diff --git a/core/src/main/java/feign/codec/ErrorDecoder.java b/core/src/main/java/feign/codec/ErrorDecoder.java
new file mode 100644
index 000000000..ab99aa396
--- /dev/null
+++ b/core/src/main/java/feign/codec/ErrorDecoder.java
@@ -0,0 +1,159 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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 java.text.DateFormat;
+import java.text.ParseException;
+import java.text.SimpleDateFormat;
+import java.util.Collection;
+import java.util.Date;
+import java.util.Map;
+import feign.FeignException;
+import feign.Response;
+import feign.RetryableException;
+import static feign.FeignException.errorStatus;
+import static feign.Util.RETRY_AFTER;
+import static feign.Util.checkNotNull;
+import static java.util.Locale.US;
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
+import static java.util.concurrent.TimeUnit.SECONDS;
+
+/**
+ * Allows you to massage an exception into a application-specific one. Converting out to a throttle
+ * exception are examples of this in use.
+ *
+ *
+ * Ex:
+ *
+ *
+ * class IllegalArgumentExceptionOn404Decoder implements ErrorDecoder {
+ *
+ * @Override
+ * public Exception decode(String methodKey, Response response) {
+ * if (response.status() == 400)
+ * throw new IllegalArgumentException("bad zone name");
+ * return new ErrorDecoder.Default().decode(methodKey, response);
+ * }
+ *
+ * }
+ *
+ *
+ *
+ * Error handling
+ *
+ *
+ * Responses where {@link Response#status()} is not in the 2xx range are classified as errors,
+ * addressed by the {@link ErrorDecoder}. That said, certain RPC apis return errors defined in the
+ * {@link Response#body()} even on a 200 status. For example, in the DynECT api, a job still running
+ * condition is returned with a 200 status, encoded in json. When scenarios like this occur, you
+ * should raise an application-specific exception (which may be {@link feign.RetryableException
+ * retryable}).
+ *
+ *
+ * Not Found Semantics
+ *
+ * It is commonly the case that 404 (Not Found) status has semantic value in HTTP apis. While the
+ * default behavior is to raise exeception, users can alternatively enable 404 processing via
+ * {@link feign.Feign.Builder#decode404()}.
+ */
+public interface ErrorDecoder {
+
+ /**
+ * Implement this method in order to decode an HTTP {@link Response} when
+ * {@link Response#status()} is not in the 2xx range. Please raise application-specific exceptions
+ * where possible. If your exception is retryable, wrap or subclass {@link RetryableException}
+ *
+ * @param methodKey {@link feign.Feign#configKey} of the java method that invoked the request. ex.
+ * {@code IAM#getUser()}
+ * @param response HTTP response where {@link Response#status() status} is greater than or equal
+ * to {@code 300}.
+ * @return Exception IOException, if there was a network error reading the response or an
+ * application-specific exception decoded by the implementation. If the throwable is
+ * retryable, it should be wrapped, or a subtype of {@link RetryableException}
+ */
+ public Exception decode(String methodKey, Response response);
+
+ public static class Default implements ErrorDecoder {
+
+ private final RetryAfterDecoder retryAfterDecoder = new RetryAfterDecoder();
+
+ @Override
+ public Exception decode(String methodKey, Response response) {
+ FeignException exception = errorStatus(methodKey, response);
+ Date retryAfter = retryAfterDecoder.apply(firstOrNull(response.headers(), RETRY_AFTER));
+ if (retryAfter != null) {
+ return new RetryableException(
+ response.status(),
+ exception.getMessage(),
+ response.request().httpMethod(),
+ exception,
+ retryAfter);
+ }
+ return exception;
+ }
+
+ private T firstOrNull(Map> map, String key) {
+ if (map.containsKey(key) && !map.get(key).isEmpty()) {
+ return map.get(key).iterator().next();
+ }
+ return null;
+ }
+ }
+
+ /**
+ * Decodes a {@link feign.Util#RETRY_AFTER} header into an absolute date, if possible.
+ * See Retry-After format
+ */
+ static class RetryAfterDecoder {
+
+ static final DateFormat RFC822_FORMAT =
+ new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", US);
+ private final DateFormat rfc822Format;
+
+ RetryAfterDecoder() {
+ this(RFC822_FORMAT);
+ }
+
+ RetryAfterDecoder(DateFormat rfc822Format) {
+ this.rfc822Format = checkNotNull(rfc822Format, "rfc822Format");
+ }
+
+ protected long currentTimeMillis() {
+ return System.currentTimeMillis();
+ }
+
+ /**
+ * returns a date that corresponds to the first time a request can be retried.
+ *
+ * @param retryAfter String in
+ * Retry-After format
+ */
+ public Date apply(String retryAfter) {
+ if (retryAfter == null) {
+ return null;
+ }
+ if (retryAfter.matches("^[0-9]+$")) {
+ long deltaMillis = SECONDS.toMillis(Long.parseLong(retryAfter));
+ return new Date(currentTimeMillis() + deltaMillis);
+ }
+ synchronized (rfc822Format) {
+ try {
+ return rfc822Format.parse(retryAfter);
+ } catch (ParseException ignored) {
+ return null;
+ }
+ }
+ }
+ }
+}
diff --git a/core/src/main/java/feign/codec/StringDecoder.java b/core/src/main/java/feign/codec/StringDecoder.java
new file mode 100644
index 000000000..2307a7c5b
--- /dev/null
+++ b/core/src/main/java/feign/codec/StringDecoder.java
@@ -0,0 +1,36 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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 java.io.IOException;
+import java.lang.reflect.Type;
+import feign.Response;
+import feign.Util;
+import static java.lang.String.format;
+
+public class StringDecoder implements Decoder {
+
+ @Override
+ public Object decode(Response response, Type type) throws IOException {
+ Response.Body body = response.body();
+ if (body == null) {
+ return null;
+ }
+ if (String.class.equals(type)) {
+ return Util.toString(body.asReader());
+ }
+ throw new DecodeException(response.status(),
+ format("%s is not a type supported by this decoder.", type));
+ }
+}
diff --git a/core/src/main/java/feign/optionals/OptionalDecoder.java b/core/src/main/java/feign/optionals/OptionalDecoder.java
new file mode 100644
index 000000000..f641de0a2
--- /dev/null
+++ b/core/src/main/java/feign/optionals/OptionalDecoder.java
@@ -0,0 +1,52 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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.optionals;
+
+import feign.Response;
+import feign.Util;
+import feign.codec.Decoder;
+import java.io.IOException;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Objects;
+import java.util.Optional;
+
+public final class OptionalDecoder implements Decoder {
+ final Decoder delegate;
+
+ public OptionalDecoder(Decoder delegate) {
+ Objects.requireNonNull(delegate, "Decoder must not be null. ");
+ this.delegate = delegate;
+ }
+
+ @Override
+ public Object decode(Response response, Type type) throws IOException {
+ if (!isOptional(type)) {
+ return delegate.decode(response, type);
+ }
+ if (response.status() == 404 || response.status() == 204) {
+ return Optional.empty();
+ }
+ Type enclosedType = Util.resolveLastTypeParameter(type, Optional.class);
+ return Optional.ofNullable(delegate.decode(response, enclosedType));
+ }
+
+ static boolean isOptional(Type type) {
+ if (!(type instanceof ParameterizedType)) {
+ return false;
+ }
+ ParameterizedType parameterizedType = (ParameterizedType) type;
+ return parameterizedType.getRawType().equals(Optional.class);
+ }
+}
diff --git a/core/src/main/java/feign/querymap/BeanQueryMapEncoder.java b/core/src/main/java/feign/querymap/BeanQueryMapEncoder.java
new file mode 100644
index 000000000..abd830b23
--- /dev/null
+++ b/core/src/main/java/feign/querymap/BeanQueryMapEncoder.java
@@ -0,0 +1,85 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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.querymap;
+
+import feign.QueryMapEncoder;
+import feign.codec.EncodeException;
+import java.beans.IntrospectionException;
+import java.beans.Introspector;
+import java.beans.PropertyDescriptor;
+import java.lang.reflect.InvocationTargetException;
+import java.util.*;
+
+/**
+ * the query map will be generated using java beans accessible getter property as query parameter
+ * names.
+ *
+ * eg: "/uri?name={name}&number={number}"
+ *
+ * order of included query parameters not guaranteed, and as usual, if any value is null, it will be
+ * left out
+ */
+public class BeanQueryMapEncoder implements QueryMapEncoder {
+ private final Map, ObjectParamMetadata> classToMetadata =
+ new HashMap, ObjectParamMetadata>();
+
+ @Override
+ public Map encode(Object object) throws EncodeException {
+ try {
+ ObjectParamMetadata metadata = getMetadata(object.getClass());
+ Map propertyNameToValue = new HashMap();
+ for (PropertyDescriptor pd : metadata.objectProperties) {
+ Object value = pd.getReadMethod().invoke(object);
+ if (value != null && value != object) {
+ propertyNameToValue.put(pd.getName(), value);
+ }
+ }
+ return propertyNameToValue;
+ } catch (IllegalAccessException | IntrospectionException | InvocationTargetException e) {
+ throw new EncodeException("Failure encoding object into query map", e);
+ }
+ }
+
+ private ObjectParamMetadata getMetadata(Class objectType) throws IntrospectionException {
+ ObjectParamMetadata metadata = classToMetadata.get(objectType);
+ if (metadata == null) {
+ metadata = ObjectParamMetadata.parseObjectType(objectType);
+ classToMetadata.put(objectType, metadata);
+ }
+ return metadata;
+ }
+
+ private static class ObjectParamMetadata {
+
+ private final List objectProperties;
+
+ private ObjectParamMetadata(List objectProperties) {
+ this.objectProperties = Collections.unmodifiableList(objectProperties);
+ }
+
+ private static ObjectParamMetadata parseObjectType(Class type)
+ throws IntrospectionException {
+ List properties = new ArrayList();
+
+ for (PropertyDescriptor pd : Introspector.getBeanInfo(type).getPropertyDescriptors()) {
+ boolean isGetterMethod = pd.getReadMethod() != null && !"class".equals(pd.getName());
+ if (isGetterMethod) {
+ properties.add(pd);
+ }
+ }
+
+ return new ObjectParamMetadata(properties);
+ }
+ }
+}
diff --git a/core/src/main/java/feign/querymap/FieldQueryMapEncoder.java b/core/src/main/java/feign/querymap/FieldQueryMapEncoder.java
new file mode 100644
index 000000000..1e0818f5c
--- /dev/null
+++ b/core/src/main/java/feign/querymap/FieldQueryMapEncoder.java
@@ -0,0 +1,77 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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.querymap;
+
+import feign.QueryMapEncoder;
+import feign.codec.EncodeException;
+import java.lang.reflect.Field;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * the query map will be generated using member variable names as query parameter names.
+ *
+ * eg: "/uri?name={name}&number={number}"
+ *
+ * order of included query parameters not guaranteed, and as usual, if any value is null, it will be
+ * left out
+ */
+public class FieldQueryMapEncoder implements QueryMapEncoder {
+
+ private final Map, ObjectParamMetadata> classToMetadata =
+ new HashMap, ObjectParamMetadata>();
+
+ @Override
+ public Map encode(Object object) throws EncodeException {
+ try {
+ ObjectParamMetadata metadata = getMetadata(object.getClass());
+ Map fieldNameToValue = new HashMap();
+ for (Field field : metadata.objectFields) {
+ Object value = field.get(object);
+ if (value != null && value != object) {
+ fieldNameToValue.put(field.getName(), value);
+ }
+ }
+ return fieldNameToValue;
+ } catch (IllegalAccessException e) {
+ throw new EncodeException("Failure encoding object into query map", e);
+ }
+ }
+
+ private ObjectParamMetadata getMetadata(Class objectType) {
+ ObjectParamMetadata metadata = classToMetadata.get(objectType);
+ if (metadata == null) {
+ metadata = ObjectParamMetadata.parseObjectType(objectType);
+ classToMetadata.put(objectType, metadata);
+ }
+ return metadata;
+ }
+
+ private static class ObjectParamMetadata {
+
+ private final List objectFields;
+
+ private ObjectParamMetadata(List objectFields) {
+ this.objectFields = Collections.unmodifiableList(objectFields);
+ }
+
+ private static ObjectParamMetadata parseObjectType(Class type) {
+ return new ObjectParamMetadata(
+ Arrays.stream(type.getDeclaredFields())
+ .filter(field -> !field.isSynthetic())
+ .peek(field -> field.setAccessible(true))
+ .collect(Collectors.toList()));
+ }
+ }
+}
diff --git a/core/src/main/java/feign/stream/StreamDecoder.java b/core/src/main/java/feign/stream/StreamDecoder.java
new file mode 100644
index 000000000..64ee79b36
--- /dev/null
+++ b/core/src/main/java/feign/stream/StreamDecoder.java
@@ -0,0 +1,107 @@
+/**
+ * Copyright 2012-2019 The Feign Authors
+ *
+ * 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.stream;
+
+import feign.FeignException;
+import feign.Response;
+import feign.codec.Decoder;
+import java.io.Closeable;
+import java.io.IOException;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Iterator;
+import java.util.Spliterator;
+import java.util.Spliterators;
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
+import static feign.Util.ensureClosed;
+
+/**
+ * Iterator based decoder that support streaming.
+ *
+ *
+ * Example:
+ *
+ *
+ *
+ * Feign.builder()
+ * .decoder(StreamDecoder.create(JacksonIteratorDecoder.create()))
+ * .doNotCloseAfterDecode() // Required for streaming
+ * .target(GitHub.class, "https://api.github.com");
+ * interface GitHub {
+ * {@literal @}RequestLine("GET /repos/{owner}/{repo}/contributors")
+ * Stream