Extending Retrofit for Fun and Profit

This talk covers a real-world example of how Retrofit can be extended to solve app-wide problems by following the principle of Convention over Configuration.

Originally presented at the Auckland GDG (Google Developers Group).

Transcript

1. Extending Retrofit for fun and profit Matt Clarke - 13 Sep 2017, GDG Auckland
2. Retrofit 2 recap
3. // Retrofit turns your HTTP API into a Java (or Kotlin) interface public interface GitHubService { @GET("users/{user}/repos") Call<List<Repo>> listRepos(@Path("user") String user); }
4. Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .build(); GitHubService service = retrofit.create(GitHubService.class);
5. Call<List<Repo>> repos = service.listRepos("octocat"); // synchronous/blocking request Response<List<Repo>> response = repos.execute(); // do stuff with response...
6. Call<List<Repo>> repos = service.listRepos("octocat"); // asynchronous request repos.enqueue(new Callback<List<Repo>>() { @Override public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) { // do stuff with response... } @Override public void onFailure(Call<List<Repo>> call, Throwable t) { // uh oh! } });
7. Call<List<Repo>> repos = service.listRepos("octocat"); // asynchronous request repos.enqueue(new Callback<List<Repo>>() { @Override public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) { // do stuff with response... } @Override public void onFailure(Call<List<Repo>> call, Throwable t) { // uh oh! } });
9. Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .build(); GitHubService service = retrofit.create(GitHubService.class);
10. Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .addCallAdapterFactory( RxJavaCallAdapterFactory.create() ) .build(); GitHubService service = retrofit.create(GitHubService.class);
11. // Retrofit turns your HTTP API into a Java (or Kotlin) interface public interface GitHubService { @GET("users/{user}/repos") Call<List<Repo>> listRepos(@Path("user") String user); }
12. // Retrofit turns your HTTP API into a Java (or Kotlin) interface public interface GitHubService { @GET("users/{user}/repos") Observable<List<Repo>> listRepos(@Path("user") String user); }
13. Q: How does this magic work?
14. A: Call Adapters
15. WTF is a Call Adapter? • Knows how to convert Call<R> to some other type T • E.g. the RxJavaCallAdapter can convert a Call<List<Repo>> into Observable<List<Repo>>
16. WTF is a Call Adapter? public interface CallAdapter<R, T> { T adapt(Call<R> call); Type responseType(); }
17. WTF is a Call Adapter? • You also need to create a CallAdapter.Factory to give to the Retrofit.Builder • Factories create CallAdapters for a given return type in the Service interface (e.g. Observable)
18. abstract class Factory { /** * Returns a call adapter for interface methods that * return returnType, or null if it cannot be handled by * this factory. */ public abstract @Nullable CallAdapter<?, ?> get(Type returnType, Annotation[] annotations, Retrofit retrofit); // .. }
19. Case Study - Orion’s Engage App
20. ‘Engage Mobile’ Patient App • Allows patients to access different types of healthcare data • E.g. their medications and lab results
21. App Architecture Data Domain Presentation View Activities, Fragments, RecyclerViewAdapters Presenters, View Model Mappers Use Cases, Domain Models Repositories, Caching, Network Adapters e.g. Retrofit Interfaces
22. Feature-specific Retrofit Interfaces • Separate REST Interface per feature ◦ MedicationStatementsApiClient, LabResultsApiClient, ... • Singleton Retrofit instance
23. interface MedicationStatementsApiClient { @Headers("Accept: application/json") @POST(".") fun getMedicationStatements(@Body query: GqlQuery): Observable<MedicationsResponse> } Feature-specific Retrofit Interfaces
24. MedicationsRepository GetMedicationsUseCase MedicationsPresenter MedicationsFragment MedicationStatementsApiClient Internet Observable<MedicationsResponse> Observable<Medication> Observable<Medication> Observable<MedicationViewModel>
25. Problem: Network Error handling • Only 3 types of “network error” should be shown to the user: ◦ Internet Connection error ◦ Server error ◦ Unknown error (everything else) • The RxJavaCallAdapter just forwards low-level network Exceptions via onError()!
26. MedicationsRepository GetMedicationsUseCase MedicationsPresenter MedicationsFragment MedicationStatementsApiClient Internet Observable<MedicationsResponse> Observable<MedicationViewModel> onError(java.net.ConnectException) onError(java.net.ConnectException)
27. Problem: Network Error handling medsObservable.subscribe(object : Observer<Medication> { override fun onNext(medication: Medication) { // add to meds list... } override fun onCompleted() {} override fun onError(e: Throwable) { when (e) { is SocketTimeoutException -> showNoConnectionToServerError() is ConnectException -> showNoConnectionToServerError() is UnknownHostException -> showNoNetworkConnectionError() is HttpException -> makeSenseOfHttpResponseCode(e) else -> showGenericNetworkError() } } })
28. Network Error Handling sealed class NetworkError(cause: Throwable?) : Throwable(cause) { class NetworkUnreachableError(cause: Throwable? = null) : NetworkError(cause) class ServerUnreachableError(cause: Throwable? = null) : NetworkError(cause) class GenericNetworkError(cause: Throwable? = null) : NetworkError(cause) }
29. Network Error Handling fun mapNetworkError(input: Throwable): Throwable { if (!networkAccessAvailable()) return NetworkError.NetworkUnreachableError(input) return when (input) { is SocketTimeoutException -> NetworkError.ServerUnreachableError(cause = input) is ConnectException -> NetworkError.ServerUnreachableError(cause = input) is UnknownHostException -> NetworkError.NetworkUnreachableError(cause = input) is HttpException -> mapHttpException(input) else -> input } }
30. Network Error Handling medicationsObservable .onErrorResumeNext { e -> Observable.error(mapNetworkError(e)) } .subscribe(object : Observer<Medication> { // .. })
31. Solution: Extend Retrofit!
32. interface MedicationStatementsApiClient { @Headers("Accept: application/json") @POST(".") fun getMedicationStatements(@Body query: GqlQuery): Observable<MedicationsResponse> }
33. interface MedicationStatementsApiClient { @Headers("Accept: application/json") @POST(".") fun getMedicationStatements(@Body query: GqlQuery): Observable<MedicationsResponse> }
34. goo.gl/YcA25T
35. Basic idea: Custom CallAdapter that wraps an RxJavaCallAdapter
36. WTF is a Call Adapter? public interface CallAdapter<R, T> { T adapt(Call<R> call); Type responseType(); }
37. class RxCallAdapterWrapper(val wrappedAdapter: CallAdapter<*>, val errorMapper: (Throwable) -> Throwable) : CallAdapter<Observable<*>> { override fun responseType(): Type = wrappedAdapter.responseType() override fun <R> adapt(call: Call<R>): Observable<*> { val observable = wrappedAdapter.adapt(call) as Observable<*> return observable.onErrorResumeNext { throwable -> Observable.error(errorMapper(throwable)) } } }
38. abstract class Factory { /** * Returns a call adapter for interface methods that * return returnType, or null if it cannot be handled by * this factory. */ public abstract @Nullable CallAdapter<?, ?> get(Type returnType, Annotation[] annotations, Retrofit retrofit); // .. }
39. class RxErrorMappingCallAdapterFactory private constructor( val errorMapper: (Throwable) -> Throwable) : CallAdapter.Factory() { companion object { fun create(errorMapper: (Throwable) -> Throwable) = RxErrorMappingCallAdapterFactory(errorMapper) } private val originalFactory = RxJavaCallAdapterFactory.create() override fun get(returnType: Type, annotations: Array<out Annotation>, retrofit: Retrofit): CallAdapter<Observable<*>> = RxCallAdapterWrapper( originalFactory.get(returnType, annotations, retrofit), errorMapper ) }
40. Retrofit.Builder() .baseUrl(baseUrl) .client(httpClient) .addCallAdapterFactory(RxJavaCallAdapterFactory.create()) .addConverterFactory(ScalarsConverterFactory.create()) .addConverterFactory(GsonConverterFactory.create())
41. Retrofit.Builder() .baseUrl(baseUrl) .client(httpClient) .addCallAdapterFactory( RxErrorMappingCallAdapterFactory.create( retrofitNetworkErrorMapper) ) .addConverterFactory(ScalarsConverterFactory.create()) .addConverterFactory(GsonConverterFactory.create())
42. medsObservable.subscribe(object : Observer<Medication> { override fun onNext(medication: Medication) { // add to meds list... } override fun onCompleted() {} override fun onError(e: Throwable) { when (e) { is SocketTimeoutException -> showNoConnectionToServerError() is ConnectException -> showNoConnectionToServerError() is UnknownHostException -> showNoNetworkConnectionError() is HttpException -> makeSenseOfHttpResponseCode(e) else -> showGenericNetworkError() } } })
43. medsObservable.subscribe(object : Observer<Medication> { override fun onNext(medication: Medication) { // add to meds list... } override fun onCompleted() {} override fun onError(e: Throwable) { when (e) { is NetworkError.NetworkUnreachableError -> showNetworkErrorView() is NetworkError.ServerUnreachableError -> showServerErrorView() else -> showUnknownErrorView() } } })
44. Conclusion • Having to remember = red flag • Convention over configuration • Good libraries are often extensible • Don’t be afraid of checking out the source of your favourite open source libs
45. Thanks! Q+A Twitter: @kiwiandroiddev