feign.Contract Maven / Gradle / Ivy
/**
* 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;
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.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.
*/
// TODO: break this and correct spelling at some point
List parseAndValidatateMetadata(Class targetType);
abstract class BaseContract implements Contract {
@Override
public List parseAndValidatateMetadata(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());
if (targetType.getInterfaces().length == 1) {
checkState(targetType.getInterfaces()[0].getInterfaces().length == 0,
"Only single-level inheritance supported: %s",
targetType.getSimpleName());
}
Map result = new LinkedHashMap();
for (Method method : targetType.getMethods()) {
if (method.getDeclaringClass() == Object.class ||
(method.getModifiers() & Modifier.STATIC) != 0 ||
Util.isDefault(method)) {
continue;
}
MethodMetadata metadata = parseAndValidateMetadata(targetType, method);
checkState(!result.containsKey(metadata.configKey()), "Overrides unsupported: %s",
metadata.configKey());
result.put(metadata.configKey(), metadata);
}
return new ArrayList<>(result.values());
}
/**
* @deprecated use {@link #parseAndValidateMetadata(Class, Method)} instead.
*/
@Deprecated
public MethodMetadata parseAndValidatateMetadata(Method method) {
return parseAndValidateMetadata(method.getDeclaringClass(), method);
}
/**
* Called indirectly by {@link #parseAndValidatateMetadata(Class)}.
*/
protected MethodMetadata parseAndValidateMetadata(Class targetType, Method method) {
MethodMetadata data = new MethodMetadata();
data.returnType(Types.resolve(targetType, targetType, method.getGenericReturnType()));
data.configKey(Feign.configKey(targetType, method));
if (targetType.getInterfaces().length == 1) {
processAnnotationOnClass(data, targetType.getInterfaces()[0]);
}
processAnnotationOnClass(data, targetType);
for (Annotation methodAnnotation : method.getAnnotations()) {
processAnnotationOnMethod(data, methodAnnotation, method);
}
checkState(data.template().method() != null,
"Method %s not annotated with HTTP method type (ex. GET, POST)",
method.getName());
Class[] parameterTypes = method.getParameterTypes();
Type[] genericParameterTypes = method.getGenericParameterTypes();
Annotation[][] parameterAnnotations = method.getParameterAnnotations();
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 (parameterTypes[i] == URI.class) {
data.urlIndex(i);
} else if (!isHttpAnnotation) {
checkState(data.formParams().isEmpty(),
"Body parameters cannot be used with form parameters.");
checkState(data.bodyIndex() == null, "Method has too many Body parameters: %s", method);
data.bodyIndex(i);
data.bodyType(Types.resolve(targetType, targetType, genericParameterTypes[i]));
}
}
if (data.headerMapIndex() != null) {
checkMapString("HeaderMap", parameterTypes[data.headerMapIndex()],
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())) {
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
Type[] interfaces = ((Class) genericType).getGenericInterfaces();
if (interfaces != null) {
for (Type extended : interfaces) {
if (ParameterizedType.class.isAssignableFrom(extended.getClass())) {
// use the first extended interface we find.
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) {
Collection names =
data.indexToName().containsKey(i) ? data.indexToName().get(i) : new ArrayList();
names.add(name);
data.indexToName().put(i, names);
}
}
class Default extends BaseContract {
static final Pattern REQUEST_LINE_PATTERN = Pattern.compile("^([A-Z]+)[ ]*(.*)$");
@Override
protected void processAnnotationOnClass(MethodMetadata data, Class targetType) {
if (targetType.isAnnotationPresent(Headers.class)) {
String[] headersOnType = targetType.getAnnotation(Headers.class).value();
checkState(headersOnType.length > 0, "Headers annotation was empty on type %s.",
targetType.getName());
Map> headers = toMap(headersOnType);
headers.putAll(data.template().headers());
data.template().headers(null); // to clear
data.template().headers(headers);
}
}
@Override
protected void processAnnotationOnMethod(MethodMetadata data,
Annotation methodAnnotation,
Method method) {
Class annotationType = methodAnnotation.annotationType();
if (annotationType == RequestLine.class) {
String requestLine = RequestLine.class.cast(methodAnnotation).value();
checkState(emptyToNull(requestLine) != null,
"RequestLine annotation was empty on method %s.", method.getName());
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",
method.getName()));
} else {
data.template().method(HttpMethod.valueOf(requestLineMatcher.group(1)));
data.template().uri(requestLineMatcher.group(2));
}
data.template().decodeSlash(RequestLine.class.cast(methodAnnotation).decodeSlash());
data.template()
.collectionFormat(RequestLine.class.cast(methodAnnotation).collectionFormat());
} else if (annotationType == Body.class) {
String body = Body.class.cast(methodAnnotation).value();
checkState(emptyToNull(body) != null, "Body annotation was empty on method %s.",
method.getName());
if (body.indexOf('{') == -1) {
data.template().body(body);
} else {
data.template().bodyTemplate(body);
}
} else if (annotationType == Headers.class) {
String[] headersOnMethod = Headers.class.cast(methodAnnotation).value();
checkState(headersOnMethod.length > 0, "Headers annotation was empty on method %s.",
method.getName());
data.template().headers(toMap(headersOnMethod));
}
}
@Override
protected boolean processAnnotationsOnParameter(MethodMetadata data,
Annotation[] annotations,
int paramIndex) {
boolean isHttpAnnotation = false;
for (Annotation annotation : annotations) {
Class annotationType = annotation.annotationType();
if (annotationType == Param.class) {
Param paramAnnotation = (Param) annotation;
String name = paramAnnotation.value();
checkState(emptyToNull(name) != null, "Param annotation was empty on param %s.",
paramIndex);
nameParam(data, name, paramIndex);
Class expander = paramAnnotation.expander();
if (expander != Param.ToStringExpander.class) {
data.indexToExpanderClass().put(paramIndex, expander);
}
data.indexToEncoded().put(paramIndex, paramAnnotation.encoded());
isHttpAnnotation = true;
if (!data.template().hasRequestVariable(name)) {
data.formParams().add(name);
}
} else if (annotationType == QueryMap.class) {
checkState(data.queryMapIndex() == null,
"QueryMap annotation was present on multiple parameters.");
data.queryMapIndex(paramIndex);
data.queryMapEncoded(QueryMap.class.cast(annotation).encoded());
isHttpAnnotation = true;
} else if (annotationType == HeaderMap.class) {
checkState(data.headerMapIndex() == null,
"HeaderMap annotation was present on multiple parameters.");
data.headerMapIndex(paramIndex);
isHttpAnnotation = true;
}
}
return isHttpAnnotation;
}
private static Map> toMap(String[] input) {
Map> result =
new LinkedHashMap>(input.length);
for (String header : input) {
int colon = header.indexOf(':');
String name = header.substring(0, colon);
if (!result.containsKey(name)) {
result.put(name, new ArrayList(1));
}
result.get(name).add(header.substring(colon + 1).trim());
}
return result;
}
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy