In the past few days and weeks we've shown you a lot of details on how to work with Retrofit 2. In this and the next blog post we'll show you a significant component of Retrofit: converters.
If converters don't take your breath away, you might find a more interesting topic in our extensive list of Retrofit topics:
Retrofit Series Overview
- Getting Started and Creating an Android Client
- Basics of API Description
- Creating a Sustainable Android Client
- URL Handling, Resolution and Parsing
- How to Change API Base Url at Runtime
- Multiple Server Environments (Develop, Staging, Production)
- Share OkHttp Client and Converters between Retrofit Instances
- Upgrade Guide from 1.9
- Beyond Android: Retrofit for Java Projects
- How to use OkHttp 3 with Retrofit 1
- Synchronous and Asynchronous Requests
- Send Objects in Request Body
- Add Custom Request Header
- Manage Request Headers in OkHttp Interceptor
- Dynamic Request Headers with @HeaderMap
- Multiple Query Parameters of Same Name
- Optional Query Parameters
- Send Data Form-Urlencoded
- Send Data Form-Urlencoded Using FieldMap
- How to Add Query Parameters to Every Request
- Add Multiple Query Parameter With QueryMap
- How to Use Dynamic Urls for Requests
- Constant, Default and Logic Values for POST and PUT Requests
- Cancel Requests
- Reuse and Analyze Requests
- Optional Path Parameters
- How to Send Plain Text Request Body
- Customize Network Timeouts
- How to Trust Unsafe SSL certificates (Self-signed, Expired)
- Dynamic Endpoint-Dependent Interceptor Actions
- How to Update Objects on the Server (PUT vs. PATCH)
- How to Delete Objects on the Server
- Introduction to (Multiple) Converters
- Adding & Customizing the Gson Converter
- Implementing Custom Converters
- How to Integrate XML Converter
- Access Mapped Objects and Raw Response Payload
- Supporting JSON and XML Responses Concurrently
- Handling of Empty Server Responses with Custom Converter
- Send JSON Requests and Receive XML Responses (or vice versa)
- Unwrapping Envelope Responses with Custom Converter
- Wrapping Requests in Envelope with Custom Converter
- Define a Custom Response Converter
Integrating Standard Converters
In order to make the communication work between the Android client and the server, they need to agree on a common data representation format. Over the years developers have introduced various formats with each their own purpose, advantages and disadvantages. What all formats have in common is that you need to map Java objects into the standard format. In Retrofit 2, this task of mapping between Java objects and the standard format is done by converters. Converters can support two directions here: from Java object to standard format (requests) and vice versa: from the standard format to Java objects (responses).
Since there are so many formats and libraries to support them, the Retrofit creators provide a list of converters. We can’t go through every single one of them, so we just give you an overview. The retrofit-converters directory lists all official response converter implementations:
Gson
Gson is for JSON mapping and can be added with the following dependency:
compile 'com.squareup.retrofit2:converter-gson:2.5.0'
SimpleXML
SimpleXML is for XML mapping. You’ll need the following line for your build.gradle:
compile 'com.squareup.retrofit2:converter-simplexml:2.5.0'
Jackson
Jackson is an alternative to Gson and claims to be faster in mapping JSON data. The setup offers you a lot more customization and might be worth a look. You can add it with:
compile 'com.squareup.retrofit2:converter-jackson:2.5.0'
Moshi
Moshi is another alternative to Gson. It’s created by the developers of Retrofit. Moshi is based on Gson, but differentiates itself with some simplifications. If you want to give this young new player on the market a try, add it with:
compile 'com.squareup.retrofit2:converter-moshi:2.5.0'
Protobuf
Protobuf is build for the format Protocol Buffers, which is a new mechanism of serializing structured data. Protocol Buffers is a new generation and comes with a lot of upside. If your API already utilizes it, you can quickly add support on the app side with:
compile 'com.squareup.retrofit2:converter-protobuf:2.5.0'
Wire
Wire is also for the Protocol Buffers format. It’s developed by the creators of Retrofit and brings their vision of code to this converter. If you’re interested, take a look by adding the dependency:
compile 'com.squareup.retrofit2:converter-wire:2.5.0'
Scalars
Finally, if you’re overwhelmed by all these complex data structures and just want to map the basic Java primitives, you can use Scalars:
compile 'com.squareup.retrofit2:converter-scalars:2.5.0'
Retrofit is open and allows other converters. For example, we’ll look into developing our own custom converter in a future blog post. Of course, you can provide your converter to the developer community and expand the list of available converters. One excellent third-party library is this converter, which adds support for the Logan Square JSON serialization library. While Retrofit makes it very easy to support multiple data formats, there are a few things you need to keep in mind in order to preserve everything working.
Dealing with Multiple Converters
Retrofit accepts various structured data formats by outsourcing the conversion of those to independent converters. These converters usually only have one specific purpose. For example, Gson deals with the JSON format, while SimpleXML transforms XML data. Retrofit makes it easy by allowing the developer to call addConverterFactory() on the Retrofit builder multiple times. As long as the converters are conflict free, e.g. Gson vs. SimpleXML, there won’t be any issues. But what happens if you add two converters, which do more or less the same job, e.g. Moshi vs. Gson?
Retrofit has a simple way of dealing with this issue. First of all, it checks with every converter if it’s able to deal with this specific data type. If the passed converter cannot understand some data, it won’t be considered for the request (but will be asked again for the next request). The order of checks is done by first-come first-serve. That means the first converter you pass to Retrofit with addConverterFactory() will be checked first. If the first converter accepts the challenge, the rest of the list will not be asked.
Effectively, this means that you need to be very careful when adding the converters! Make sure you **specify the special-purpose converters with limited abilities first and general converters (like Gson) last.
Outlook
In this blog post, you've learned what Retrofit uses converters for mapping data for various standard formats to and from Java objects. You've also seen an overview of all provided standard converters. Finally, you understand how to deal with multiple formats.
In the next blog post, we'll go deeper into the JSON converter and show you how to customize the Gson mapping.
