Internal talk given at Orion Health on extending Retrofit (an open source HTTP client) with your own Call Adapter for centralised error handling.

1. Extending Retrofit for fun
and profit
Matt Clarke - 4 July 2017, Orion Health Akl

2. Retrofit (v2.1.0) 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);
}
Define a light-weight interface that matches the REST endpoint you want to talk to

4. Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
GitHubService service =
retrofit.create(GitHubService.class);
Now you can use a Retrofit instance to generate a working version of your interface
to make requests with

5. Call<List<Repo>> repos = service.listRepos("octocat");
// synchronous/blocking request
Response<List<Repo>> response = repos.execute();
// do stuff with response...
To actually make a request, you just call the method you defined in your interface.
You’ll get back a Call object.
You can use this to make a sync request like this...

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!
}
});
Or you can use Call objects to make an asynchronous requests by calling enqueue
and passing a callback

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!
}
});
You might notice there are some similarities here with a library we’re all familiar with.
This Callback object looks a lot like an RxJava Observer or Subscriber.
Wouldn’t it be cool if the service returned an Observable instead of a Call? Then we
could go nuts with operators, subscribing on a different thread, etc.

8. Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
GitHubService service = retrofit.create(GitHubService.class);

9. Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.addCallAdapterFactory(
RxJavaCallAdapterFactory.create()
)
.build();
GitHubService service = retrofit.create(GitHubService.class);

10. // 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);
}

11. // 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);
}

12. Q: How does this magic work?

13. A: Call Adapters

14. WTF is a Call Adapter?
● Knows how to convert Call<R> to some other
type T
● E.g. the RxJavaCallAdapter can convert a
Call<Repo> into Observable<Repo>

15. WTF is a Call Adapter?
public interface CallAdapter<R, T> {
T adapt(Call<R> call);
Type responseType();
}

16. WTF is a Call Adapter?
● You also need to create a
CallAdapter.Factory to give to the
Retrofit.Builder
● Factories are given the chance to create
CallAdapters for a given return type in the
Service interface (e.g. Observable)

17. 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);
// ..
}

18. Concrete example - Engage Mobile

19. Problem: Network Error handling
● The RxJavaCallAdapter just forwards low-level network
Exceptions via onError()

20. Problem: Network Error handling
val repoObservable = service.listRepos("octocat")
repoObservable.subscribe(object : Observer<List<Repo>> {
override fun onNext(repos: List<Repo>) {
// show repos in UI...
}
override fun onCompleted() {}
override fun onError(e: Throwable) {
when (e) {
is SocketTimeoutException -> showTimeoutError()
is ConnectException -> showNoConnectionToServerError()
is UnknownHostException -> showNoNetworkConnectionError()
is HttpException -> makeSenseOfHttpResponseCode(e)
}
}
})
You need to handle all of the
possible network errors
somewhere in order to do the
right thing in the UI.
Don’t want to have a copy of this
`when` statement everywhere
there’s a network call.
Also, these errors are low-level
and depend on the HTTP client
you’re using: if you change
HTTP libraries you don’t want all
of your UI code to break - they’re
separate concerns.

21. 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)
} Solution: abstract away low-level HTTP client errors by defining your own
higher-level network error types

22. Network Error Handling
fun map(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
}
}
...Then you can extract out a common network error mapper,
and apply this to the reactive stream with the
onErrorResumeNext operator

23. Network Error Handling
repoObservable
.onErrorResumeNext { e ->
Observable.error(mapNetworkError(e))
}
.subscribe(object : Observer<List<Repo>> {
// ..
})
The problem with this is you still need to remember to apply this
mapper to all reactive streams that contain a network request.
Having to remember = a red flag. Better to structure the system
such that it does the right thing by default (remembers for you)

24. Live code demo