About Molly Android: A technical overview

Molly Android is a native Android front-end adaptation of the Molly Framework, the original code was created on the Molly Project Github by Chris Northwood and coding only started when I (Sean) joined the OUCS team as a summer intern in July 2011. In this wiki page, I will try to give you a technical overview of how it works.

1. The "Router"

The idea of Molly Android is to replicate the structure of the Molly framework: a larger backbone and can be adapted to be used in many different ways easily like Molly to Mobile Oxford. The code available here is the backbone, plus an actual implementation of Mobile Oxford. This overview will hopefully give you an idea of how the project is structured. Let’s start with the backbone. Molly Android is basically a web app, so the very core of the whole project is a class called Router which is solely responsible for communicating between the web server and the client app itself. In short, the Router receives the actions from the user and then passes on the requests to the server via 3 main methods:

 public String getFrom (String urlStr) //is the basic method for GET requests

 public synchronized JSONObject onRequestSent(String locator, String arg, OutputFormat format, String query) 
 //performs a series of requests  and returns the JSON representation of the requested content

 public List<String> post(List<NameValuePair> arguments, String url) 
 //is the basic method for POST requests

All of these methods use an HttpClient. More details for each method will be available in the upcoming Javadoc.) The Router also holds a reference to a LocationTracker and is responsible for updating the current location of the device as well. Session details can also be found in and is managed by the CookieManager which is stored in Router.

Different applications of Molly may use different data interchange formats, but Mobile Oxford currently supports JSON the most extensively, so it is safe for now to stick with JSON, but preparations have also been made for future changes, thus the OutputFormat argument in the onRequestSent() method. Future changes may mean that this method can only return String instead of JSONObject as it does now (which means every request made has a “?format=json” query sent to the Molly server).

2. MyApplication and MollyModule

It takes 2 more important support classes to keep the system running before moving to the user interface: MollyModule and MyApplication. Firstly, MyApplication is a subclass of Application. Molly Android uses this class as its “application” (as specified in the AndroidManifest.xml file), which means the whole application lives as one instance under MyApplication, and MyApplication stays the same whatever the Activity that calls it is. More importantly, MyApplication also lives along with the application’s lifecycle, so it actually gets created and destroyed along with the application itself. And for those reason, this is where all the intermediate data should go, e.g. when communications between 2 Activities are needed (a particular example is the case when the user enters a search string and is taken to a results page that requests the result from the server and renders it, the search query cannot be passed directly from one Activity to another so it is cached in MyApplication under some static field.)

At this point, note that Molly Android uses Google Guice and RoboGuice for dependency injections. And this is the second use of MyApplication along with MollyModule: it has an Injector which asks for a class and a key, then returns either the subclass of the specified class or the instance/value of that class which is bound with the key in MollyModule. This is very helpful in various cases: during the process of coding, one may not remember very large/auto-generated integers (as in gen/R.java) used for ids of layouts, colours, drawables, etc so an easy-to-remember human-readable string can be bound to such integers and recalled later by the injector reduces the hassle. In terms of dependency injection, the coder may not be happy with a currently implemented page (for example, someone from Bangor wants to use their class org.bangor.android.places.PlacesPage.java rather than org.mollyproject.android.places.PlacesPage.java, they don’t need to go and change every single place that makes a reference to org.mollyproject.android.places.PlacesPage.java in the whole project, they only need to change the bindings in MollyModule, and all subsequent reference to the Page that is bound via the String “places:index” is led to whatever they specified. One line of code changed – that is very neat, and also the idea behind Molly Android, why it is called Molly Android, not Mobile Oxford Android, all people need to do is to customise it (this doesn’t mean the customisation is easy, unfortunately)

3. User Interface

Moving on to the user interface, I don’t really want to talk too much about it here, but as an overview, the class responsible for the user interface in MollyAndroid is called a Page (as I’ve mentioned above) that extends Activity. Most of the pages are actually ContentPage, which contains a contentLayout where all the views should be added to. Any Page should be accompanied by a BackgroundTask (extending AsyncTask) that runs in the background, takes the characteristic values from the Page it is associated to, directly talks to the Router, takes the JSON received from Router and renders the needed views and adds them to the page. In other words, the Page supplies the BackgroundTask whatever it needs (queries, arguments, etc – note that these cannot all stay in the BackgroundTask because a Page may use several different BackgroundTasks) and the BackgroundTask goes on and deals with the Router, comes back and update the views on the Page.

A ContentPage is often updated via a couple of BackgroundTasks called when the page resumes: a PageSetupTask that retrieves the JSON using the supplied parameters from the page, this method mostly deals with the breadcrumbs, and the second BackgroundTask which varies from Page to Page, may or may not use the JSON data from PageSetupTask, generates the rest of the content in contentLayout. These 2 tasks are created almost simultaneously with the second one waiting for the first one to complete downloading the requested JSON before actually running (this is the first and most basic in a series of synchronisations applied to these tasks)