AeroGear Pipes in Android

Let’s say you have a simple webservice at http://www.server.com/developer. This service has the following API:

and the JSON retrieved via get http verb

to marshals for this class

PipeManager class is used to instantiate and manage a Pipe object. You don’t have to keep a reference to the result. Pipeline.get(String, Activity) will return a instance of LoaderPipe which is really a wrapper around the original Pipe object. There are also Pipeline.get methods for Fragments classes

Here is an example of using the Pipe API to retrieve the JSON payload shown earlier. Note that the library will automatically marshall the payload to your model, leaving you only with task to display the results in the UI. Further and equally important, it will respect the Activity (or Fragment) lifecycle, a common source of problem bugging Android developers as we will discuss next

You need to be aware of the Android Activity lifecycle. If the Application goes into the background (ex. the user gets a phone call), then any results which come in may be lost or cause an Exception if they interact with the UI of the suspended Activity. If there is a configuration change (ex. the phone was rotated) then the Activity is destroyed and a new one is created. If you used an anonymous inner class for your CallBack instance then you will lose your results when the operation completes (because anonymous inner classes have an implicit reference to the outer class).

However, AeroGear also has support for Android’s Loader API. Loader’s were introduced by Android in version 3.0, and their lifecycle is managed by Android. When an Activity is paused and resumed, any activity the Loader was working on is returned. If the Activity is destroyed because of a configuration change then the Loader will provide its results to the new Activity instance without having to make second call to a remote server.

The pipe instance will be respectful of the Android lifecycle and calls to its methods will be handled by and behave like Loaders. For instance, if the device is rotated the result of the read will be returned from a local cache instead of being fetched from the web again. If you want to force a read, just call pipe.reset() before your read.

AeroGear on Android uses a class called Pipe to retrieve data from a source asynchronously. A Pipe has the methods read, readWithFilter, remove, and save. A Pipe implementation is responsible for managing PipeHandler instances, processing their results and returning the results to the user via callbacks provided by the Pipe CRUD methods. AG Android has two Pipe implementations: RestAdapter and LoaderAdapter.

PipeHandler instances are responsible for connecting to a remote source, sending a request, fetching the response, and returning a deserialized instance of that result to the Pipe which requested it. PipeHandler do not need to worry about threading, this is the responsibility of the Pipe.

So why separate Pipe and PipeHandler? The logic of threading is troublesome and often leads to bugs. The patterns and trade offs are usually specific to Android and not your application. Since AeroGear provides this logic along with methods for selecting the most appropriate mechanisms for handling threads, there is no reason to burden a developer with it. The methods for connecting to remote services are much more specific to the use case (IE the app). If our default implementations do not fit your needs, it is much simpler to implement a PipeHandler and allow a Pipe to manage the threading for you.

For many of the cases, writing an adapter to a remote source which AG can not support is as simple as implementing a PipeHandler and passing it to a Pipe.

Pipe uses PipeHandler to interact with services. The default PipeHandler is RestRunner, the RestRunner delegates requests for GsonRequestBuilder and response parse to GsonResponseParser

Behind the scenes, GsonRequestBuilder and GsonResponseParser uses Google’s GSON for JSON object serialization and deserialization. Both have a construction to consume a GSON instance. This GSON will be used to marshall and unmarshall objects. If you have nested, typed collections, etc. You can configure a GSON which supports your data model and pass it to the GsonRequestBuilder and GsonResponseParser

Sometimes you will have a simple result format, but your data will be surrounded by metadata. Take this JSON snippet for example:

In this example you are interested in the data object’s "children" collection. Instead of writing code using GSON to fetch it, you can instead configure a GsonResponseParser and MarshallingConfig.