Specific usage analysis of Android Retrofit source code

[[170834]]

Introduction

Retrofit is an HTTP framework launched by Square, mainly used in Android and Java. Retrofit converts network requests into method calls, which is very simple and convenient to use. This article first briefly introduces the usage of Retrofit, and then specifically analyzes the execution process of its source code.

Basic Usage

Retrofit turns HTTP API into Java interface. Here is an example from Retrofit official website:

 public interface GitHubService {
  @GET( "users/{user}/repos" )
  Call<List<Repo>> listRepos(@Path( "user" ) String user );
 }

In the GithubService interface, there is a method listRepos, which is annotated with @GET, indicating that this is a GET request. The users/{user}/repos in the brackets at the end is the path of the request, where {user} indicates that this part is dynamically changing, and its value is passed by the method parameter, and the parameter @Path("user") String user of this method is used to replace {user}. Also note that the return value of this method is Call<List<Repo>>. It can be seen that Retrofit uses annotations to describe the parameters related to a network request.

The above is just the beginning. Now we need to make this network request:

 Retrofit retrofit = new Retrofit.Builder()
 .baseUrl( "https://api.github.com/" )
 .addConverterFactory(GsonConverterFactory. create ())
 .build(); 
 
 GitHubService service = retrofit. create (GitHubService. class);
 Call<List<Repo>> repos = service.listRepos( "octocat" );
 repos.enqueue(new Callback<List<Repo>>() {
 @Override
 public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) { 
             
 }
 @Override
 public void onFailure(Call<List<Repo>> call, Throwable t) { 
 
 }
 });

It can be seen that a Retrofit object is first constructed, in which the baseUrl parameter is passed in. The baseUrl and the path after the above GET method are combined to form a complete URL. In addition to baseUrl, there is also a converterFactory, which is used to convert the returned http response into a Java object, corresponding to the return value of the method Call<List<Repo>> in List<Repo>>, where Repo is a custom class. With the Retrofit object, call its create method to create an instance of GitHubService, and then call the method of this instance to request the network. Call the listRepo method to get a Call object, and then use enqueue or execute to initiate the request. enqueue is asynchronous execution, while execute is synchronous execution.

This is the basic usage of Retrofit. For other details, please check the official website.

Source code analysis

When I first came into contact with Retrofit, I thought it was quite magical, and its usage was different from general network requests. Let's take a look at how the source code of Retrofit is implemented.

Retrofit creation

From the creation method of Retrofit, we can see that the Builder mode is used. There are several key variables in Retrofit:

 //Method used to cache parsed data
 private final Map<Method, ServiceMethod> serviceMethodCache = new LinkedHashMap<>(); 
  
 //The OKHttp factory for requesting the network, the default is OkHttpClient
 private final okhttp3.Call.Factory callFactory; 
  
 //baseurl
 private final HttpUrl baseUrl; 
  
 //A collection of converters for the response obtained by requesting the network. BuiltInConverters will be added by default
 private final List<Converter.Factory> converterFactories; 
  
 //Convert the Call object to other types
 private final List<CallAdapter.Factory> adapterFactories; 
  
 //Used to execute callbacks. The default in Android is MainThreadExecutor
 private final Executor callbackExecutor; 
  
 //Do you need to parse the method in the interface immediately?
 private final boolean validateEagerly; 
  

Let's take a look at the builder method of the inner class Builder in Retrofit:

 public Retrofit build() {
 if (baseUrl == null ) {
    throw new IllegalStateException( "Base URL required." );
 } 
 
  okhttp3.Call.Factory callFactory = this.callFactory;
 if (callFactory == null ) {
 //Create an OkHttpClient by default
    callFactory = new OkHttpClient();
 } 
 
  Executor callbackExecutor = this.callbackExecutor;
  if (callbackExecutor == null ) {
 // Android returns MainThreadExecutor
    callbackExecutor = platform.defaultCallbackExecutor();
 } 
 
  // Make a defensive copy of the adapters and   add the default Call adapter.
  List<CallAdapter.Factory> adapterFactories = new ArrayList<>(this.adapterFactories);
  adapterFactories.add ( platform.defaultCallAdapterFactory (callbackExecutor)); 
 
  // Make a defensive copy of the converters.
  List<Converter.Factory> converterFactories = new ArrayList<>(this.converterFactories); 
 
 return new Retrofit(callFactory, baseUrl, converterFactories, adapterFactories,
      callbackExecutor, validateEagerly);
 }

When creating Retrofit, if OkHttpClient is not specified, a default one will be created. If callbackExecutor is not specified, the platform default will be returned, which is MainThreadExecutor in Android, and a CallAdapter will be built using this to add to adapterFactories.

create method

Once you have a Retrofit object, you can create an instance of the network request interface class through the create method. The code is as follows:

 public <T> T create (final Class<T> service) {
 Utils.validateServiceInterface(service);
 if (validateEagerly) {
 //Pre-analysis method
  eagerlyValidateMethods(service);
 }
 return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class<?>[] { service },
 new InvocationHandler() {
      private final Platform platform = Platform.get(); 
 
      @Override public Object invoke(Object proxy, Method method, Object... args)
 throws Throwable {
 // If the method is a method from Object then defer to normal invocation. If it is a method in Object, call it directly
        if (method.getDeclaringClass() == Object.class) {
 return method.invoke(this, args);
 }
 //To be compatible with the Java 8 platform, this will not be executed in Android
        if (platform.isDefaultMethod(method)) {
 return platform.invokeDefaultMethod(method, service, proxy, args);
 }
 //The following is the key point, parsing method
        ServiceMethod serviceMethod = loadServiceMethod(method);
        OkHttpCall okHttpCall = new OkHttpCall<>(serviceMethod, args);
 return serviceMethod.callAdapter.adapt(okHttpCall);
 }
 });

The create method accepts a Class object, which is the interface we wrote, which contains the method for requesting the network marked by annotations. Note the return statement part, where the Proxy.newProxyInstance method is called. This is very important because the dynamic proxy mode is used. For more information about the dynamic proxy mode, you can refer to this article: http://www.codekk.com/blogs/d... A simple description is that Proxy.newProxyInstance generates an instance A, which is the proxy class, based on the Class object passed in. Whenever this proxy class A executes a method, it always calls the invoke method of InvocationHandler (the third parameter in Proxy.newProxyInstance). In this method, you can perform some operations (here, the annotation parameters of the parsing method, etc.), and through this method, the network request in the interface we wrote is actually executed.

Method resolution and type conversion

Let's take a closer look at the lines in invoke that parse the network request method. First, ServiceMethod serviceMethod = loadServiceMethod(method);, where the loadServiceMethod code is as follows:

 ServiceMethod loadServiceMethod(Method method) {
 ServiceMethod result;
    synchronized (serviceMethodCache) {
      result = serviceMethodCache.get(method);
 if (result == null ) {
        result = new ServiceMethod.Builder(this, method).build();
        serviceMethodCache.put(method, result);
 }
 }
 return result;
 }

It can be seen that the cache is searched first, and no further creation is done in the cache. A ServiceMethod object is created here. ServiceMethod is used to convert the call of the interface method into an HTTP request. In fact, in ServiceMethod, the annotations and parameters of the method in the interface are parsed, and it also has a toRequest method to generate a Request object. This Request object is the Request in OkHttp, which represents a network request (Retrofit actually entrusts the actual network request operation to OkHttp for execution). The following is part of the code to create ServiceMethod:

 public ServiceMethod build() {
 //Get callAdapter
  callAdapter = createCallAdapter();
  responseType = callAdapter.responseType();
  if (responseType == Response.class || responseType == okhttp3.Response.class) {
 throw methodError( "'"  
        + Utils.getRawType(responseType).getName()
        + "' is not a valid response body type. Did you mean ResponseBody?" );
 }
 //Get responseConverter
  responseConverter = createResponseConverter(); 
 
 for (Annotation annotation : methodAnnotations) {
 //Analysis annotation
    parseMethodAnnotation(annotation);
 //Some code omitted
 ...
 }
 }

After getting the ServiceMethod object, pass it and the relevant parameters of the method call to the OkHttpCall object, which is this line of code: OkHttpCall okHttpCall = new OkHttpCall<>(serviceMethod, args);. The following introduces OkHttpCall, which inherits from the Call interface. Call is the basic interface of Retrofit, representing sending network requests and response calls. It contains the following interface methods:

• Response<T> execute() throws IOException; //Synchronous execution request
• void enqueue(Callback<T> callback); //Asynchronous execution request, callback is used for callback
• boolean isExecuted(); //Has it been executed?
• void cancel(); //Cancel request
• boolean isCanceled(); //Is it canceled?
• Call<T> clone(); //Clone a request
• Request request(); //Get the original request

OkHttpCall is an implementation class of Call, which encapsulates the native Call in OkHttp. Methods such as execute and enqueue are implemented in this class, which actually calls the corresponding methods of the native Call in OkHttp.

Next, pass OkHttpCall to the serviceMethod.callAdapter object. What is callAdapter here? In the code that creates ServiceMethod above, there is a line of code: callAdapter = createCallAdapter(). Here, calladapter is created. Inside this code, the corresponding CallAdapter is found based on the return type and annotation of the method. Where to find it? Find it in the adapterFactories collection of the Retrofit object. When we create Retrofit, we can call addCallAdapter to add CallAdapter to adapterFactories. In the previous basic usage, we did not add any CallAdapter, but an ExecutorCallAdapterFactory will be added to adapterFactories by default. Calling its get method can get the CallAdapter object.

So what does CallAdapter do? The adapt method is called above, which is to convert a Call to another type. For example, when Retrofit is used in combination with RxJava, the method in the interface can return Observable<T>, which is equivalent to the adapter pattern. By default, a Call object is obtained, which is ExecutorCallbackCall. The code is as follows:

 public CallAdapter<Call<?>> get(Type returnType, Annotation[] annotations, Retrofit retrofit) {
 if (getRawType(returnType) != Call.class) {
 return   null ;
 }
 final Type responseType = Utils.getCallResponseType(returnType);
 return new CallAdapter<Call<?>>() {
  @Override public Type responseType() {
 return responseType;
 } 
 
  @Override public <R> Call<R> adapt(Call<R> call) {
 return new ExecutorCallbackCall<>(callbackExecutor, call);
 }
 };
 }

This ExecutorCallbackCall accepts a callbackExecutor (MainThreadExecutor by default in Android, which passes the returned data back to the main thread) and a call, which is OkhttpCall. Look at the ExecutorCallbackCall code:

 static final class ExecutorCallbackCall<T> implements Call<T> {
 final Executor callbackExecutor;
 final Call<T> delegate; 
 
 ExecutorCallbackCall(Executor callbackExecutor, Call<T> delegate) {
  this.callbackExecutor = callbackExecutor;
 this.delegate = delegate;
 } 
 
 @Override public void enqueue(final Callback<T> callback) {
  if (callback == null ) throw new NullPointerException( "callback == null" ); 
 
  delegate.enqueue(new Callback<T>() {
    @Override public void onResponse(Call<T> call, final Response<T> response) {
      callbackExecutor. execute (new Runnable() {
        @Override public void run() {
          if (delegate.isCanceled()) {
            // Emulate OkHttp's behavior of throwing/delivering an IOException on cancellation.
            callback.onFailure(ExecutorCallbackCall.this, new IOException( "Canceled" ));
 } else {
            callback.onResponse(ExecutorCallbackCall.this, response);
 }
 }
 });
 } 
 
    @Override public void onFailure(Call<T> call, final Throwable t) {
      callbackExecutor. execute (new Runnable() {
        @Override public void run() {
          callback.onFailure(ExecutorCallbackCall.this, t);
 }
 });
 }
 });
 }

In the enqueue method, the enqueue of OkHttpCall is called, so this is equivalent to the static proxy mode. The enqueue in OkHttpCall actually calls the enqueue in the native OkHttp, where the network request is actually issued. Some of the code is as follows:

 @Override public void enqueue(final Callback<T> callback) {
    if (callback == null ) throw new NullPointerException( "callback == null" );
 //The actual call to the network
 okhttp3.Call call;
 Throwable failure; 
 
 synchronized (this) {
      if (executed) throw new IllegalStateException( "Already executed." );
 executed = true ;
 //Some code is omitted
 ...
 call = rawCall;
 //enqueue asynchronous execution
    call.enqueue(new okhttp3.Callback() {
      @Override public void onResponse(okhttp3.Call call, okhttp3.Response rawResponse)
          throws IOException {
 Response<T> response;
 try {
 // Parsing data will use converterFactory to convert the response to the corresponding Java type
          response = parseResponse(rawResponse);
        } catch (Throwable e) {
 callFailure(e);
 return ;
 }
        callSuccess(response);
 } 
 
      @Override public void onFailure(okhttp3.Call call, IOException e) {
 try {
          callback.onFailure(OkHttpCall.this, e);
        } catch (Throwable t) {
          t.printStackTrace();
 }
 } 
 
  private void callFailure(Throwable e) {
 try {
      callback.onFailure(OkHttpCall.this, e);
 } catch (Throwable t) {
 t.printStackTrace();
 }
 } 
 
  private void callSuccess(Response<T> response) {
 try {
      callback.onResponse(OkHttpCall.this, response);
 } catch (Throwable t) {
 t.printStackTrace();
 }
 }
 });
 }

After OkHttp obtains the data, it parses the data and calls back the callback response method, and a network request is completed.

Summarize

The code of the entire Retrofit framework is not too long and is relatively easy to read. It mainly uses dynamic proxy to parse the Java interface into the corresponding network request, and then sends it to OkHttp for execution. It can also adapt to different CallAdapters and can be easily used in combination with RxJava.