Retrofit三步理解之三 ------------------ Retrofit完整使用分析

package com.mycroft.retrofitdemo;

import okhttp3.*;
import retrofit2.*;
import retrofit2.Call;
import retrofit2.http.*;
import retrofit2.http.Field;

import java.io.IOException;
import java.lang.annotation.Annotation;
import java.lang.reflect.*;
import java.util.Arrays;
import java.util.concurrent.Executor;
import java.util.concurrent.Executors;

/**
* Created by Mycroft on 2016/2/1.
*/
public class Main {

public static void main(String[] args) throws IOException {
RemoteService remoteService = RemoteService.getInstance();
String data = remoteService.getBaidu().getData();
System.out.println(data);

System.out.println(remoteService.getString().execute().body());
}
}

/**
* {@link retrofit2.Retrofit.Builder#callbackExecutor(Executor)} 的解释：
* 无论是否调用{@link retrofit2.Retrofit.Builder#addCallAdapterFactory(CallAdapter.Factory)}, {@link Retrofit}都会添加一个
* {@link CallAdapter}作为默认的。
* 如果没有使用这个方法，那{@link Retrofit} 会根据Android和Java平台生成一个相应的网络请求的回调{@link Executor}，
* 在Android平台会生成一个回调在主线程中执行的{@link retrofit2.CallAdapter}, 在Java平台会生成一个默认在{@link OkHttpClient}回调池中的{@link CallAdapter}
* 而如果使用了这个方法，那么生成的默认{@link CallAdapter}的回调则会在该{@link Executor}指定的线程池中执行。
*/
class RemoteService {

private static RemoteService sRemoteService;
private final Retrofit mRetrofit;
private final IApiService mService;

public static RemoteService getInstance() {
if (sRemoteService == null) {
synchronized (RemoteService.class) {
if (sRemoteService == null) {
sRemoteService = new RemoteService();
}
}
}
return sRemoteService;
}

private final OkHttpClient mHttpClient;

private RemoteService() {
mHttpClient = new OkHttpClient.Builder().build();
mRetrofit = new Retrofit.Builder()
.client(mHttpClient)        // client()在内部会直接调用callFactory方法，即，将OkHttpClient作为默认网络请求框架，根据实际情况可以改变(几乎不会)
.callFactory(mHttpClient)   // 如上所属
.addConverterFactory(new DemoConverterAdapterFactory())        // 详看 DemoConverterAdapterFactory
.addConverterFactory(GsonConverterFactory.create())         // Retrofit自己实现的GsonConverterFactory
.addCallAdapterFactory(RxJavaCallAdapterFactory.create())   // 详看 DemoCallAdapter
.addCallAdapterFactory((Type returnType, Annotation[] annotations, Retrofit retrofit) ->{
if ((returnType instanceof ParameterizedType) && Util.getRawType(returnType) == Encapsulation.class) {
return new DemoCallAdapter(returnType);
}
return null;
})
.callbackExecutor(Executors.newCachedThreadPool())      // 一句话不足以说明，见头部注释
.validateEagerly(true)          // 目前的理解是：当构造一个interface代理时，马上对其进行解析，而不是使用的时候再加载，加快了速度
.baseUrl("http://www.baidu.com/")   // 不解释
.build();

mService = mRetrofit.create(IApiService.class);
}

public Encapsulation<String> getBaidu() {
return mService.getBaidu();
}

public Call<String> getString(){
return mService.getString();
}
}

class Encapsulation<T> {
private final T mData;

public Encapsulation(T data) {
mData = data;
}

public T getData() {
return mData;
}
}

/**
* {@link CallAdapter}默认有两个方法：
* 1. {@link CallAdapter#responseType()} 返回此{@link CallAdapter}能够处理的数据类型
* 2. {@link CallAdapter#adapt(Call)} 将默认返回的{@link Call}转换成需要的数据类型
*
* {@link Retrofit}默认的网络请求返回类型是{@link Call}, 自然地，{@link Retrofit}有一个默认的{@link CallAdapter}
* 这个方法直接在{@link CallAdapter#adapt(Call)}中返回网络请求的结果，即{@link Call}类型。
*
* 有时(别人写好的情况下，谁没事干自己写)，我们更期望另外的数据类型，例如结合RxJava使用，将其转换成{@link rx.Observable}对象，
* 那么就需要实现{@link CallAdapter}, 将{@link Call}转换为我们需要的数据类型。
*
* 如何实现{@link CallAdapter}:
* {@link retrofit2.CallAdapter.Factory#get(Type, Annotation[], Retrofit)}的参数{@link Type}参数是
* {@link CallAdapter#responseType()}的返回类型，而{@link Retrofit}要求{@link CallAdapter#responseType()}的返回类型是其中的包裹类型，
* 例如Call<String>中的{@link String}
* 概念：
* 1. {@link Retrofit}期望的是一个{@link retrofit2.CallAdapter.Factory}对象
* 2. 判断{@link retrofit2.CallAdapter.Factory#get(Type, Annotation[], Retrofit)}的参数{@link Type}是否是我们需要被转换的类型，
* 注意这里是需要将{@link Type}拆分，因为{@link Type}是一个泛型对象，传进来的类型示例：com.mycroft.retrofitdemo.Encapsulation<java.lang.String>
* 我们不会对泛型的参数类型做处理。
* 根据拆分得到的包裹类型(例如com.mycroft.retrofitdemo.Encapsulation)判断是否是我们需要的，如果是，则返回对应的{@link CallAdapter}
* 3. 实现{@link CallAdapter}: {@link CallAdapter}中有两个方法, {@link CallAdapter#responseType()}返回
*/
class DemoCallAdapter implements CallAdapter<Encapsulation<?>> {

private Type mReturnType;

public DemoCallAdapter(Type returnType) {
mReturnType = returnType;
//        System.out.println(mReturnType.getTypeName());
}

@Override
public Type responseType() {
return Util.getParameterUpperBound(0, (ParameterizedType) mReturnType);
}

@Override
public <R> Encapsulation<R> adapt(Call<R> call) {
try {
return new Encapsulation<>(call.execute().body());
} catch (IOException e) {
e.printStackTrace();
return null;
}
}
}

interface IApiService {
@GET("/")
Encapsulation<String> getBaidu();

@GET("/")
Call<String> getString();
}

/**
* 抽象类{@link retrofit2.Converter.Factory}有三个方法，分别是:
* 1. 转换网络请求结果 {@link retrofit2.Converter.Factory#responseBodyConverter(Type, Annotation[], Retrofit)}
* 2. 转换网络请求参数 {@link retrofit2.Converter.Factory#requestBodyConverter(Type, Annotation[], Retrofit)}
* 3. 转换网络请求参数 {@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])}
* <p>
* 解释：
* 1. {@link Retrofit}对{@link retrofit2.Converter.Factory}的处理:
* <code>
*     int start = converterFactories.indexOf(skipPast) + 1;
*     for (int i = start, count = converterFactories.size(); i < count; i++) {
*          Converter<?, RequestBody> converter =
*              converterFactories.get(i).requestBodyConverter(type, annotations, this);
*              if (converter != null) {
*                  //noinspection unchecked
*                  return (Converter<T, RequestBody>) converter;
*              }
*     }
*     ...
*     throw new IllegalArgumentException(builder.toString());
* </code>
* 跳过skipPast，一般而言start都是为0, 从上述代码可以看出，{@link Retrofit}是遍历所有的{@link retrofit2.Converter.Factory},
* 从中找到一个不为null的{@link Converter}并返回，如果没有找到，将抛出一个{@link IllegalArgumentException}
*
* 2. {@link Retrofit}对于{@link retrofit2.Converter.Factory#responseBodyConverter(Type, Annotation[], Retrofit)},
* {@link retrofit2.Converter.Factory#requestBodyConverter(Type, Annotation[], Retrofit)},
* {@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])}
* 的处理几乎都是一样的，除了{@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])},
* 在{@link java.util.List<retrofit2.Converter.Factory>}中寻找一个合适的{@link retrofit2.Converter.Factory},
* 返回找到的第一个{@link retrofit2.Converter.Factory}, 如果没找到，将抛出异常,
* 而{@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])} 在没找到的情况下不会抛出异常，
* 而是返回一个BuiltIn的{@link retrofit2.Converter.Factory}, 直接调用需要被转换参数的{@link Object#toString()}方法
*
* 3. {@link retrofit2.Converter.Factory#requestBodyConverter(Type, Annotation[], Retrofit)}和
* {@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])} 的区别
*
* {@link retrofit2.Converter.Factory#requestBodyConverter(Type, Annotation[], Retrofit)}处理以下注解的参数
* {@link Body @Body}, {@link Part @Part}, and {@link PartMap @PartMap}
*
* {@link retrofit2.Converter.Factory#stringConverter(Type, Annotation[])}处理以下注解的参数
* {@link Field @Field}, {@link FieldMap @FieldMap} values,
* {@link Header @Header}, {@link Path @Path}, {@link Query @Query}, and
* {@link QueryMap @QueryMap} values.
*/
class DemoConverterAdapterFactory extends Converter.Factory {

/**
* 这个方法是将ResponseBody转换为?类型，?的类型是参数{@link Type}
* 用于将网络请求的数据(以{@link ResponseBody}的形式被包裹)转换成需要的数据类型
*
* @param type        需要的数据类型，实际上就是一个Class对象
* @param annotations todo
* @param retrofit
* @return 对于参数type的一个合适的{@link Converter}对象
*/
@Override
public Converter<ResponseBody, ?> responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
System.out.println("converter: " + type.getTypeName());
if (type == String.class) {
return value -> value.string();
}
return null;
}

/**
* @param type        需要被转换的数据类型，实际上就是一个Class对象
* @param annotations
* @param retrofit
* @return 对于参数type的一个合适的{@link Converter}对象
*/
@Override
public Converter<?, RequestBody> requestBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
return super.requestBodyConverter(type, annotations, retrofit);
}

/**
* @param type        需要被转换的数据类型，实际上就是一个Class对象
* @param annotations
* @return 对于参数type的一个合适的{@link Converter}对象
*/
@Override
public Converter<?, String> stringConverter(Type type, Annotation[] annotations) {
return super.stringConverter(type, annotations);
}
}

class Util{
public static Class<?> getRawType(Type type) {
if (type instanceof Class<?>) {
// Type is a normal class.
return (Class<?>) type;

} else if (type instanceof ParameterizedType) {
ParameterizedType parameterizedType = (ParameterizedType) type;

// I'm not exactly sure why getRawType() returns Type instead of Class. Neal isn't either but
// suspects some pathological case related to nested classes exists.
Type rawType = parameterizedType.getRawType();
if (!(rawType instanceof Class)) throw new IllegalArgumentException();
return (Class<?>) rawType;

} else if (type instanceof GenericArrayType) {
Type componentType = ((GenericArrayType) type).getGenericComponentType();
return Array.newInstance(getRawType(componentType), 0).getClass();

} else if (type instanceof TypeVariable) {
// We could use the variable's bounds, but that won't work if there are multiple. Having a raw
// type that's more general than necessary is okay.
return Object.class;

} else if (type instanceof WildcardType) {
return getRawType(((WildcardType) type).getUpperBounds()[0]);

} else {
String className = type == null ? "null" : type.getClass().getName();
throw new IllegalArgumentException("Expected a Class, ParameterizedType, or "
+ "GenericArrayType, but <" + type + "> is of type " + className);
}
}

public static Type getParameterUpperBound(int index, ParameterizedType type) {
Type[] types = type.getActualTypeArguments();
if (types.length <= index) {
throw new IllegalArgumentException(
"Expected at least " + index + " type argument(s) but got: " + Arrays.toString(types));
}
Type paramType = types[index];
if (paramType instanceof WildcardType) {
return ((WildcardType) paramType).getUpperBounds()[0];
}
return paramType;
}
}