Retrofit 2.0: By far the biggest update to the best Android HTTP client library

Objective

From the work of square company of mobile payment company, the smallest company of open source World top5, first I myself is a loyal square powder, okhttp, Picasso, Greendao, Okio and so on ~
According to the square CTO Bob Lee, Square has submitted more than 60 projects to the open source community, contributing around 250,000 lines of code.

Original: Retrofit 2.0:the biggest update yet on the best HTTP Client Library for Android

Because of its simplicity and excellent performance, Retrofit is one of the most popular HTTP client libraries on Android.

However, its disadvantage is that there is no way to cancel the ongoing task directly in retrofit 1.x. If you want to do this you have to kill it manually, and that is not a good implementation.

Square had promised that this feature would be implemented in retrofit 2.0 a few years ago, but that a few years later has not been updated on this issue.

Until last week, Retrofit 2.0 became Beta 1 from the candidate release stage and was publicly available to everyone. After trying, I had to say I was impressed with the new model and the new features. There are many improvements that this article will discuss. Let's get started!

The bag or the package, just a new version.
If you want to import retrofit 2.0 into your own project, add this line of code in the Dependencies section of Build.gradle:

Compile ' com.squareup.retrofit:retrofit:2.0.0-beta1 '
You can use retrofit 2.0 after the Sync gradle file.

New service definition mode, no longer synchronous and asynchronous
As for the definition of the service interface in retrofit 1.9, if you want to define a synchronous function, you should define this:

/* Synchronous in Retrofit 1.9 */publicinterface APIService {    @POST("/list")    Repo loadRepo();}

And the definition of an asynchronous is this:

/* Asynchronous in Retrofit 1.9 */publicinterface APIService {    @POST("/list")    void loadRepo(Callback<Repo> cb);}

But on retrofit 2.0, you can define only one pattern, so it's much simpler.

import retrofit.Call;/* Retrofit 2.0 */publicinterface APIService {    @POST("/list")    Call<Repo> loadRepo();}

The method of creating the service also becomes the same as the okhttp pattern. If you want to invoke a synchronous request, you only need to invoke execute, and an asynchronous request is called Enqueue.

Sync Request

Call in Retrofit 2.0Call<Repo> call = service.loadRepo();call.execute();

The above code will block the thread, so you can't call it in the main thread of Android, or you'll face networkonmainthreadexception. If you want to invoke the Execute method, execute it in a background thread.

Asynchronous request

// Synchronous Call in Retrofit 2.0Call<Repo> call = service.loadRepo();call.enqueue(new Callback<Repo>() {    @Override    publicvoidonResponse(Response<Repo> response) {        // Get result Repo from response.body()    }    @Override    publicvoidonFailure(Throwable t) {    }});

The code above initiates a request for a background thread and obtains a result object from the response Response.body () method. Note that the Onresponse and OnFailure methods here are called in the main thread.

I suggest you use Enqueue, which best fits the Android OS habit.

Cancel a business that is in progress
The reason that the service mode becomes call is to allow the transaction in progress to be canceled. To do this, you simply call Call.cancel ().

Call.cancel ();
The transaction will be canceled immediately thereafter. Good simple Hey!

Converter now removed from retrofit
In retrofit 1.9, Gsonconverter is included in the package and is automatically initialized when Restadapter is created. The son result from the server is automatically parsed into a defined data Access Object (DAO)

However, in retrofit 2.0, Converter is no longer included in the package. You need to insert a converter yourself, otherwise retrofit can only receive string results. Similarly, Retrofit 2.0 is no longer dependent on Gson.

If you want to receive JSON results and parse into DAO, you must add Gson Converter as a standalone dependency.

‘com.squareup.retrofit:converter-gson:2.0.0-beta1‘

Then use Addconverterfactory to add it in. Note that the alias for Restadapter is still retrofit.

Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://api.nuuneoi.com/base/")        .addConverterFactory(GsonConverterFactory.create())        .build();service = retrofit.create(APIService.class);

This is the official Converter modules list provided by Square. Choose the one that best meets your needs.

Gson: com. Squareup. Retrofit: Converter-gsonJackson: com. Squareup. Retrofit: Converter-jacksonMoshi: com. Squareup. Retrofit: Converter-moshiProtobuf: com. Squareup. Retrofit: Converter-protobufWire : com. Squareup. Retrofit: Converter-wiresimple XML:com. Squareup. Retrofit: Converter-simplexml

You can also create a custom converter by implementing the Converter.factory interface.

I am quite in favor of this new model. It makes retrofit seem clearer about what he wants to do.

Customizing Gson objects
In case you need to adjust some of the formatting in the JSON, for example, Date format. You can create a Gson object and pass it to Gsonconverterfactory.create ().

Gson gson = new GsonBuilder()        .setDateFormat("yyyy-MM-dd‘T‘HH:mm:ssZ")        .create();Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://api.nuuneoi.com/base/")        .addConverterFactory(GsonConverterFactory.create(gson))        .build();service = retrofit.create(APIService.class);

Complete.

New ways to define URLs
Retrofit 2.0 uses the new URL definition method. The Base Url is not a simple combination of @url, but is consistent with the way "". This is illustrated in a few examples below.

1, PS: It seems that the second one to meet the habit.

For the new URL definition in Retrofit 2.0, here is my suggestion:

• Base URL: Always end with/

• @Url: Do not start with/

Like what

publicinterface APIService {    @POST("user/list")    Call<Users> loadUsers();}publicvoiddoSomething() {    new Retrofit.Builder()            .baseUrl("http://api.nuuneoi.com/base/")            .addConverterFactory(GsonConverterFactory.create())            .build();    APIService service = retrofit.create(APIService.class);}

The loadusers in the above code will fetch data from http://api.nuuneoi.com/base/user/list.

And in retrofit 2.0 we can also define the full URL in @url:

publicinterface APIService {    @POST("http://api.nuuneoi.com/special/user/list")    Call<Users> loadSpecialUsers();}

In this case, the base URL is ignored.

You can see a big change in how URLs are handled. It is completely different from the previous version. If you want to migrate your code to retrofit 2.0, don't forget to fix the code in the URL section.

Now we need okhttp support.
OkHttp is optional in the retrofit 1.9. If you want retrofit to use Okhttp as an HTTP connection interface, you need to manually include okhttp dependencies.

However, in retrofit 2.0, OkHttp is required and is automatically set up in order to be dependent. The following code is crawled from the Retrofit 2.0 pom file. You don't have to do anything anymore.

<dependencies>  <dependency>    <groupId>com.squareup.okhttp</groupId>    <artifactId>okhttp</artifactId>  </dependency>  ...</dependencies>

In order for the Okhttp call mode to be possible, okhttp is automatically used as an HTTP interface in retrofit 2.0.

Onresponse is still called even if there is a problem with response
In retrofit 1.9, if the obtained response cannot be parsed into a defined object, failure is called. But in retrofit 2.0, whether or not response can be parsed. Onresponse will always be called. However, response.body () returns null if the result cannot be parsed. Don't forget to deal with this situation.

If there is something wrong with response, such as 404 or so, Onresponse will be called. You can get the body of the error message from Response.errorbody (). String ().

Response/failure logic and retrofit 1.9 are quite different. If you decide to migrate to retrofit 2.0, take care to handle these situations with caution.

Missing Internet permissions can cause SecurityException exceptions
In retrofit 1.9, if you forget to add Internet permissions in the Androidmanifest.xml file. The asynchronous request goes directly to the failure callback method and gets the permission DENIED error message. No exception was thrown.

But in retrofit 2.0, when you call Call.enqueue or Call.execute, the SecurityException will immediately be thrown, and if you don't use Try-catch it will cause a crash.

This is similar to the behavior when you call HttpURLConnection manually. But that's not a big problem, because there's nothing to think about when Internet permissions are added to Androidmanifest.xml.

Use a interceptor from OkHttp
In retrofit 1.9, you can use Requestinterceptor to intercept a request, but it has been removed from Retrofit 2.0 because the HTTP connection layer has been converted to okhttp.

As a result, we now have to use the interceptor inside the okhttp instead. First you need to create a Okhttpclient object using Interceptor, as follows:

new OkHttpClient();client.interceptors().add(new Interceptor() {    @Override    publicinterceptthrows IOException {        Response response = chain.proceed(chain.request());        // Do anything with response here        return response;    }});

The created client is then passed to the retrofit builder chain.

Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://api.nuuneoi.com/base/")        .addConverterFactory(GsonConverterFactory.create())        .client(client)        .build();

The above is the whole content.

To learn about Okhttp interceptor, please go to okhttp interceptors.

RxJava Integration with Calladapter
In addition to using the call mode to define the interface, we can also define our own type, such as Mycall. We call this mechanism of retrofit 2.0 the Calladapter.

The retrofit team has the Calladapter module already ready. One of the most famous module may be the Calladapter prepared for Rxjava, which will be returned as observable. To use it, you must include two modules in your project dependencies.

‘com.squareup.retrofit:adapter-rxjava:2.0.0-beta1‘‘io.reactivex:rxandroid:1.0.1‘

Sync Gradle and call addcalladapterfactory in the Retrofit builder list as follows:

Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://api.nuuneoi.com/base/")        .addConverterFactory(GsonConverterFactory.create())        .addCallAdapterFactory(RxJavaCallAdapterFactory.create())        .build();

Your service interface can now be returned as observable!

Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://api.nuuneoi.com/base/")        .addConverterFactory(GsonConverterFactory.create())        .addCallAdapterFactory(RxJavaCallAdapterFactory.create())        .build();

You can use it exactly like Rxjava, and if you want the subscribe part of the code to be called in the main thread, you need to add Observeon (Androidschedulers.mainthread ()) to the list.

observable<dessertitemcollectiondao> Observable = Service. Loaddessertlistrx();Observable. Observeon(androidschedulers. Mainthread()). Subscribe(New subscriber<dessertitemcollectiondao> () {@Override public void oncompleted () {Toast. Maketext(Getapplicationcontext (),"Completed", Toast. LENGTH_short). Show();} @Override public void OnError (Throwable e) {Toast. Maketext(Getapplicationcontext (), E. GetMessage(), Toast. LENGTH_short). Show();} @Override public void OnNext (Dessertitemcollectiondao dessertitemcollectiondao) {Toast. Maketext(Getapplicationcontext (), Dessertitemcollectiondao. GetData(). Get(0). GetName(), Toast. LENGTH_short). Show();}    });

Complete! I believe Rxjava's fans are quite satisfied with the change.

Summarize
There are many other changes that you can get more details in the official change Log. However, I believe I have covered the main issues in this article.

You might be wondering if it's time to switch to retrofit 2.0? Given that it is still a beta phase, you may wish to stay at 1.9 unless you are like me as a person who likes early adopters. Retrofit 2.0 It's good. In my experience, no bugs have been found.

Note the official documentation for retrofit 1.9 is now removed from the Square's GitHub homepage. I suggest you start learning Retrofit 2.0 now and use the latest version as soon as possible.

Retrofit 2.0: By far the biggest update to the best Android HTTP client library