core/src/main/java/feign/Contract.java

/*
 * 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 feign.Util.checkState;
import static feign.Util.emptyToNull;

import feign.Request.HttpMethod;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.lang.reflect.Parameter;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.net.URI;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/** Defines what annotations and values are valid on interfaces. */
public interface Contract {

  /**
   * Called to parse the methods in the class that are linked to HTTP requests.
   *
   * @param targetType {@link feign.Target#type() type} of the Feign interface.
   */
  List<MethodMetadata> parseAndValidateMetadata(Class<?> targetType);

  abstract class BaseContract implements Contract {

    /**
     * @param targetType {@link feign.Target#type() type} of the Feign interface.
     * @see #parseAndValidateMetadata(Class)
     */
    @Override
    public List<MethodMetadata> parseAndValidateMetadata(Class<?> targetType) {
      checkState(
          targetType.getTypeParameters().length == 0,
          "Parameterized types unsupported: %s",
          targetType.getSimpleName());
      checkState(
          targetType.getInterfaces().length <= 1,
          "Only single inheritance supported: %s",
          targetType.getSimpleName());
      final Map<String, MethodMetadata> result = new LinkedHashMap<String, MethodMetadata>();
      for (final Method method : targetType.getMethods()) {
        if (method.getDeclaringClass() == Object.class
            || (method.getModifiers() & Modifier.STATIC) != 0
            || Util.isDefault(method)
            || method.isAnnotationPresent(FeignIgnore.class)) {
          continue;
        }
        final MethodMetadata metadata = parseAndValidateMetadata(targetType, method);
        if (result.containsKey(metadata.configKey())) {
          MethodMetadata existingMetadata = result.get(metadata.configKey());
          Type existingReturnType = existingMetadata.returnType();
          Type overridingReturnType = metadata.returnType();
          Type resolvedType = Types.resolveReturnType(existingReturnType, overridingReturnType);
          if (resolvedType.equals(overridingReturnType)) {
            result.put(metadata.configKey(), metadata);
          }
          continue;
        }
        result.put(metadata.configKey(), metadata);
      }
      return new ArrayList<>(result.values());
    }

    /**
     * @deprecated use {@link #parseAndValidateMetadata(Class, Method)} instead.
     */
    @Deprecated
    public MethodMetadata parseAndValidateMetadata(Method method) {
      return parseAndValidateMetadata(method.getDeclaringClass(), method);
    }

    /** Called indirectly by {@link #parseAndValidateMetadata(Class)}. */
    protected MethodMetadata parseAndValidateMetadata(Class<?> targetType, Method method) {
      final MethodMetadata data = new MethodMetadata();
      data.targetType(targetType);
      data.method(method);
      data.returnType(Types.resolve(targetType, targetType, method.getGenericReturnType()));
      data.configKey(Feign.configKey(targetType, method));
      if (AlwaysEncodeBodyContract.class.isAssignableFrom(this.getClass())) {
        data.alwaysEncodeBody(true);
      }

      if (targetType.getInterfaces().length == 1) {
        processAnnotationOnClass(data, targetType.getInterfaces()[0]);
      }
      processAnnotationOnClass(data, targetType);

      for (final Annotation methodAnnotation : method.getAnnotations()) {
        processAnnotationOnMethod(data, methodAnnotation, method);
      }
      if (data.isIgnored()) {
        return data;
      }
      checkState(
          data.template().method() != null,
          "Method %s not annotated with HTTP method type (ex. GET, POST)%s",
          data.configKey(),
          data.warnings());
      final Class<?>[] parameterTypes = method.getParameterTypes();
      final Type[] genericParameterTypes = method.getGenericParameterTypes();

      final Annotation[][] parameterAnnotations = method.getParameterAnnotations();
      final int count = parameterAnnotations.length;
      for (int i = 0; i < count; i++) {
        boolean isHttpAnnotation = false;
        if (parameterAnnotations[i] != null) {
          isHttpAnnotation = processAnnotationsOnParameter(data, parameterAnnotations[i], i);
        }

        if (isHttpAnnotation) {
          data.ignoreParamater(i);
        }

        if ("kotlin.coroutines.Continuation".equals(parameterTypes[i].getName())) {
          data.ignoreParamater(i);
        }

        if (parameterTypes[i] == URI.class) {
          data.urlIndex(i);
        } else if (!isHttpAnnotation
            && !Request.Options.class.isAssignableFrom(parameterTypes[i])) {
          if (data.isAlreadyProcessed(i)) {
            checkState(
                data.formParams().isEmpty() || data.bodyIndex() == null,
                "Body parameters cannot be used with form parameters.%s",
                data.warnings());
          } else if (!data.alwaysEncodeBody()) {
            checkState(
                data.formParams().isEmpty(),
                "Body parameters cannot be used with form parameters.%s",
                data.warnings());
            checkState(
                data.bodyIndex() == null,
                "Method has too many Body parameters: %s%s",
                method,
                data.warnings());
            data.bodyIndex(i);
            data.bodyType(Types.resolve(targetType, targetType, genericParameterTypes[i]));
          }
        }
      }

      if (data.headerMapIndex() != null) {
        // check header map parameter for map type
        if (Map.class.isAssignableFrom(parameterTypes[data.headerMapIndex()])) {
          checkMapKeys("HeaderMap", genericParameterTypes[data.headerMapIndex()]);
        }
      }

      if (data.queryMapIndex() != null) {
        if (Map.class.isAssignableFrom(parameterTypes[data.queryMapIndex()])) {
          checkMapKeys("QueryMap", genericParameterTypes[data.queryMapIndex()]);
        }
      }

      return data;
    }

    private static void checkMapString(String name, Class<?> type, Type genericType) {
      checkState(Map.class.isAssignableFrom(type), "%s parameter must be a Map: %s", name, type);
      checkMapKeys(name, genericType);
    }

    private static void checkMapKeys(String name, Type genericType) {
      Class<?> keyClass = null;

      // assume our type parameterized
      if (ParameterizedType.class.isAssignableFrom(genericType.getClass())) {
        final Type[] parameterTypes = ((ParameterizedType) genericType).getActualTypeArguments();
        keyClass = (Class<?>) parameterTypes[0];
      } else if (genericType instanceof Class<?>) {
        // raw class, type parameters cannot be inferred directly, but we can scan any extended
        // interfaces looking for any explict types
        final Type[] interfaces = ((Class<?>) genericType).getGenericInterfaces();
        for (final Type extended : interfaces) {
          if (ParameterizedType.class.isAssignableFrom(extended.getClass())) {
            // use the first extended interface we find.
            final Type[] parameterTypes = ((ParameterizedType) extended).getActualTypeArguments();
            keyClass = (Class<?>) parameterTypes[0];
            break;
          }
        }
      }

      if (keyClass != null) {
        checkState(
            String.class.equals(keyClass),
            "%s key must be a String: %s",
            name,
            keyClass.getSimpleName());
      }
    }

    /**
     * Called by parseAndValidateMetadata twice, first on the declaring class, then on the target
     * type (unless they are the same).
     *
     * @param data metadata collected so far relating to the current java method.
     * @param clz the class to process
     */
    protected abstract void processAnnotationOnClass(MethodMetadata data, Class<?> clz);

    /**
     * @param data metadata collected so far relating to the current java method.
     * @param annotation annotations present on the current method annotation.
     * @param method method currently being processed.
     */
    protected abstract void processAnnotationOnMethod(
        MethodMetadata data, Annotation annotation, Method method);

    /**
     * @param data metadata collected so far relating to the current java method.
     * @param annotations annotations present on the current parameter annotation.
     * @param paramIndex if you find a name in {@code annotations}, call {@link
     *     #nameParam(MethodMetadata, String, int)} with this as the last parameter.
     * @return true if you called {@link #nameParam(MethodMetadata, String, int)} after finding an
     *     http-relevant annotation.
     */
    protected abstract boolean processAnnotationsOnParameter(
        MethodMetadata data, Annotation[] annotations, int paramIndex);

    /** links a parameter name to its index in the method signature. */
    protected void nameParam(MethodMetadata data, String name, int i) {
      final Collection<String> names =
          data.indexToName().containsKey(i) ? data.indexToName().get(i) : new ArrayList<String>();
      names.add(name);
      data.indexToName().put(i, names);
    }
  }

  class Default extends DeclarativeContract {

    static final Pattern REQUEST_LINE_PATTERN = Pattern.compile("^([A-Z]+)[ ]*(.*)$");

    public Default() {
      super.registerClassAnnotation(
          Headers.class,
          (header, data) -> {
            final String[] headersOnType = header.value();
            checkState(
                headersOnType.length > 0,
                "Headers annotation was empty on type %s.",
                data.configKey());
            final Map<String, Collection<String>> headers = toMap(headersOnType);
            headers.putAll(data.template().headers());
            data.template().headers(null); // to clear
            data.template().headers(headers);
          });
      super.registerMethodAnnotation(
          RequestLine.class,
          (ann, data) -> {
            final String requestLine = ann.value();
            checkState(
                emptyToNull(requestLine) != null,
                "RequestLine annotation was empty on method %s.",
                data.configKey());

            final Matcher requestLineMatcher = REQUEST_LINE_PATTERN.matcher(requestLine);
            if (!requestLineMatcher.find()) {
              throw new IllegalStateException(
                  String.format(
                      "RequestLine annotation didn't start with an HTTP verb on method %s",
                      data.configKey()));
            } else {
              data.template().method(HttpMethod.valueOf(requestLineMatcher.group(1)));
              data.template().uri(requestLineMatcher.group(2));
            }
            data.template().decodeSlash(ann.decodeSlash());
            data.template().collectionFormat(ann.collectionFormat());
          });
      super.registerMethodAnnotation(
          Body.class,
          (ann, data) -> {
            final String body = ann.value();
            checkState(
                emptyToNull(body) != null,
                "Body annotation was empty on method %s.",
                data.configKey());
            if (body.indexOf('{') == -1) {
              data.template().body(body);
            } else {
              data.template().bodyTemplate(body);
            }
          });
      super.registerMethodAnnotation(
          Headers.class,
          (header, data) -> {
            final String[] headersOnMethod = header.value();
            checkState(
                headersOnMethod.length > 0,
                "Headers annotation was empty on method %s.",
                data.configKey());
            data.template().headers(toMap(headersOnMethod));
          });
      super.registerParameterAnnotation(
          Param.class,
          (paramAnnotation, data, paramIndex) -> {
            final String annotationName = paramAnnotation.value();
            final Parameter parameter = data.method().getParameters()[paramIndex];
            final String name;
            if (emptyToNull(annotationName) == null && parameter.isNamePresent()) {
              name = parameter.getName();
            } else {
              name = annotationName;
            }
            checkState(
                emptyToNull(name) != null,
                "Param annotation was empty on param %s.\nHint: %s",
                paramIndex,
                "Prefer using @Param(value=\"name\"), or compile your code with the -parameters flag.\n"
                    + "If the value is missing, Feign attempts to retrieve the parameter name from bytecode, "
                    + "which only works if the class was compiled with the -parameters flag.");
            nameParam(data, name, paramIndex);
            final Class<? extends Param.Expander> expander = paramAnnotation.expander();
            if (expander != Param.ToStringExpander.class) {
              data.indexToExpanderClass().put(paramIndex, expander);
            }
            if (!data.template().hasRequestVariable(name)) {
              data.formParams().add(name);
            }
          });
      super.registerParameterAnnotation(
          QueryMap.class,
          (queryMap, data, paramIndex) -> {
            checkState(
                data.queryMapIndex() == null,
                "QueryMap annotation was present on multiple parameters.");
            data.queryMapIndex(paramIndex);
            data.queryMapEncoder(queryMap.mapEncoder().instance());
          });
      super.registerParameterAnnotation(
          HeaderMap.class,
          (queryMap, data, paramIndex) -> {
            checkState(
                data.headerMapIndex() == null,
                "HeaderMap annotation was present on multiple parameters.");
            data.headerMapIndex(paramIndex);
          });
    }

    private static Map<String, Collection<String>> toMap(String[] input) {
      final Map<String, Collection<String>> result =
          new LinkedHashMap<String, Collection<String>>(input.length);
      for (final String header : input) {
        final int colon = header.indexOf(':');
        final String name = header.substring(0, colon);
        if (!result.containsKey(name)) {
          result.put(name, new ArrayList<String>(1));
        }
        result.get(name).add(header.substring(colon + 1).trim());
      }
      return result;
    }
  }
}