Episode II: Customizing serialization using the gson library in the Mobile Services Android client

04 March 2013

Welcome to part two of my blog series about the new Mobile Services Android client SDK. Here are the other posts in the series:

Working with typed and untyped data
Customizing serialization using the gson library
Exploring the richness of the query model
Implementing authentication correctly
Intercepting HTTP traffic for fun and profit
Unit testing your client code
Advanced push scenarios

Today let’s focus on customizing object serialization using the gson library, which the Android client library uses under the covers to serialize objects to JSON data. In the previous episode of this series we named our Java object in lowercase, so all the properties would get serialized that way on the wire:

public class droid {
    public Integer id;
    public String name;
    public Float weight;
    public Integer numberOfLegs;
    public Integer numberOfWheels;
}

For all of you seasoned Java developers out there, this immediately sticks out as bad programming style: we’re not capitalizing things correctly and also we’re not using getters and setters. This next class uses gson’s serialization attributes to produce the exact same wire representation as above.

public class Droid {
    
    @com.google.gson.annotations.SerializedName("id")
    private Integer mId;
    @com.google.gson.annotations.SerializedName("name")	
    private String mName;
    @com.google.gson.annotations.SerializedName("weight")	
    private Float mWeight;
    @com.google.gson.annotations.SerializedName("numberOfLegs")	
    private Integer mNumberOfLegs;
    @com.google.gson.annotations.SerializedName("numberOfWheels")	
    private Integer mNumberOfWheels;
	
    public Integer getId() { return mId; }
    public final void setId(Integer id) { mId = id; }
	
    public String getName() { return mName; }
    public final void setName(String name) { mName = name; }
	
    public Float getWeight() { return mWeight; }
    public final void setWeight(Float weight) { mWeight = weight; }
	
    public Integer getNumberOfLegs () { return mNumberOfLegs; }
    public final void setNumberOfLegs(Integer numberOfLegs) { 
        mNumberOfLegs = numberOfLegs; 
        }
	
    public Integer getNumberOfWheels() { return mNumberOfWheels; }
    public final void setNumberOfWheels(Integer numberOfWheels) { 
        mNumberOfWheels = numberOfWheels; 
        }	
}

There is another catch here… our type name is Droid (uppercase), but maybe we want our table name to be lowercase. It’s just a matter of which getTable overload we use.

// Assumes table name is "Droid"
MobileServiceTable table = client.getTable(Droid.class);
// Allows you to use table named "droid" - use this one!
MobileServiceTable table = client.getTable("droid", Droid.class);

This was a relatively simple serialization trick. To do more we need to whip out the big gun: GsonBuilder. To successfully talk to your mobile service, the client needs to do some customizations of its own, so we we need to get a pre-cofigured instance from the the MobileServiceClient.createMobileServiceGsonBuilder() static method. We can then add our own modifications and pass the instance back to the client. The below code does a lot in just a few lines:

It enables pretty-printing for our output JSON
It turns on automatic property lower-casing, so we can remove the @com.google.gson.annotations.SerializedName annotations from our type definition above. All that copy pasting was making me feel like an attack of the clones (sorry couldn’t come up with a better pun here…)

client.setGsonBuilder(
    MobileServiceClient
    .createMobileServiceGsonBuilder()
    .setFieldNamingStrategy(new FieldNamingStrategy() {
        public String translateName(Field field) {
            String name = field.getName();
            return Character.toLowerCase(name.charAt(1))
                + name.substring(2);
            }
        })
        .setPrettyPrinting());

Of course we need to add the above code before the calls to any of the methods on the client.

To really put the cherry on the cake, let’s tackle a very challenging problem: complex types. So far all of our properties have neatly serialized to JSON primitives. Imagine we want to add the following property on our Droid object:

private ArrayList&lt;String&gt; mCatchphrases;
    
public ArrayList&lt;String&gt; getCatchphrases() {
    if(mCatchphrases == null){
        mCatchphrases = new ArrayList&lt;String&gt;();
    }
    return mCatchphrases;
}
private final void setCatchphrases(ArrayList&lt;String&gt; catchphrases){
    mCatchphrases = catchphrases;
}

Having objects and arrays as properties is a rather advanced feature mostly because we now have to a make a call about how those are represented on the server. Mobile Services doesn’t support that out-of-the-box and you would get an error similar to this one:

{
    "code":400,
    "error":"Error: The value of property 'catchphrases' is of type 'object' which is not a supported type."
}

Let’s roll our own custom solution. On serialization we will store the JSON-serialized representation of our complex properties inside JSON strings. On the server, we will simply store the strings inside a string column. On deserialization, we will parse those strings as JSON and deserialize them back into typed objects. A tall order!

Our strategy here is to register a custom serializer for ArrayList<T> types. Here is an implementation I put together:

import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.Collection;

import com.google.gson.JsonArray;
import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonParseException;
import com.google.gson.JsonParser;
import com.google.gson.JsonPrimitive;
import com.google.gson.JsonSerializationContext;
import com.google.gson.JsonSerializer;

public class CollectionSerializer&lt;E&gt; implements 
JsonSerializer&lt;Collection&lt;E&gt;&gt;, JsonDeserializer&lt;Collection&lt;E&gt;&gt;{

    public JsonElement serialize(Collection&lt;E&gt; collection, Type type,
            JsonSerializationContext context) {
        JsonArray result = new JsonArray();
        for(E item : collection){
            result.add(context.serialize(item));
        }
        return new JsonPrimitive(result.toString());
    }

	
    @SuppressWarnings("unchecked")
    public Collection&lt;E&gt; deserialize(JsonElement element, Type type,
            JsonDeserializationContext context) throws JsonParseException {
        JsonArray items = (JsonArray) new JsonParser().parse(element.getAsString());
        ParameterizedType deserializationCollection = ((ParameterizedType) type);
        Type collectionItemType = deserializationCollection.getActualTypeArguments()[0];
        Collection&lt;E&gt; list = null;
		
        try {
            list = (Collection&lt;E&gt;)((Class&lt;?&gt;) deserializationCollection.getRawType()).newInstance();
            for(JsonElement e : items){
                list.add((E)context.deserialize(e, collectionItemType));
            }
        } catch (InstantiationException e) {
            throw new JsonParseException(e);
        } catch (IllegalAccessException e) {
            throw new JsonParseException(e);
        }
		
        return list;
    }
}

This code is only slightly magical, read through it if you want to stretch your understanding of Java generics. This only covers collections, I’ve left doing the same for classes as an exercise to the reader.

We now need to register the serializer. MobileServiceClient provides a convenience method for you here:

client.registerSerializer(ArrayList.class, new CollectionSerializer&lt;Object&gt;());

All that does is add it to your GsonBuilder instance using the identically named method.

That’s it for today, in the next post we’ll dive into the query model.