JSON-able domain objects

JSON has arguably become the new lingua franca of the Internet; that is, JSON has become preferable for browser to server communication — over that of XML, which, as it happens, is quite verbose. JSON’s lightweight-ness makes it easily readable and easy to parse.

For example, in the case of a Retweet object (which represents a Twitter retweet), I can represent it easily enough in JSON like so:

   {
     "screenname":"BarackObama",
     "influence":5901913,
     "date":"2010-11-11"
     "tweet":"I want our veterans to know: We remember...",
     "tweetid":2758011831459840,
     "picture":"http://a3.twimg.com/profile_images/784...",
     "username":"Barack Obama"
    }

JSON is simple — in fact, it looks a lot like a map. There are names, which have values. This makes representing something like a domain object quite simple. Don’t let JSON’s simpleness fool you either — JSON can represent lists, which can also be values, just as easily.

Compare this same data represented as XML:

<retweet>
  <screenname>BarackObama</screenname>
  <influence>5901913</influence>
  <date>2010-11-11</date>
  <tweet>"I want our veterans to know: We remember..."</tweet>
  <tweetid>2758011831459840</tweetid>
  <picture>http://a3.twimg.com/profile_images/784...</picture>
  <username>"Barack Obama"</username>
</retweet>

As you can see, JSON is a bit less verbose and easier to visually comprehend the corresponding data. Of course, JSON’s terseness also facilitates communication in a era where Ajax calls increasingly tax browser processing and network bandwidth.

Just as java.lang,Object‘s toString method provides a convenient mechanism for codifying, albeit sometimes cryptically, an object, I find it helpful to make domain objects in a web application JSON-able via a toJSON method. Accordingly, I can enforce a JSON-able contract via an interface like so:

public interface JSONable {
  String toJSON();
}

Then, I have my domain objects implement this interface; what’s more, I provide the behavior of JSON-ness via a handy library known as JSON-lib. This library has a simple, low-level API for creating JSON structures. For example, to represent a Retweet, my toJSON method looks like:

public String toJSON() {
  JSONObject json = new JSONObject();
  json.put("screenname", this.screenName);
  json.put("influence", this.influence);
  json.put("date", this.getFormattedDate());
  json.put("tweet", this.tweet);
  json.put("tweetid", this.tweetId);
  json.put("picture", this.userPicture);
  json.put("username", this.userName);
  return json.toString();
}

Note, in this case, I’ve chosen to have explicit control over how my JSON document will look — that is, I’m not interested in camel-casing (which I’ve obeyed in my Java code — for instance, userName is a property in Retweet, but in the JSON structure, I’ve left it as username). Thus, I’ve decided to call out each property I wish represented via JSON-lib’s JSONObject‘s put call. I’ve also left out undesired properties of my Retweet object (such as the owner, etc).

This pattern of having individual object’s represent themselves as JSON also helps when building aggregate JSON documents — for example, if I wish to represent a collection of retweets — say the top three retweets as ranked by influence, I can do so quite easily. Given a collection of three Retweet objects, making a larger JSON document containing them is as easy as:

def jsonr = new JSONObject()
jsonr.put("influencers", justthree*.toJSON())

In the code above, justthree is a List containing three Retweet objects — via Groovy’s handy dandy shortcuts, I can invoke the toJSON method on all objects within a collection with a *. (i.e. spread) invocation. This code will produce a JSON document that looks like the following (I’ve added spaces and newlines for more readability):

{
 "influencers":
   [
     {
      "screenname":"stuarthalloway",
      "influence":2310,
      "date":"2010-08-17",
      "tweet":"Podcast w/@stuarthalloway about Clojure...",
      "tweetid":21451426508,
      "picture":"http://a0.twimg.com/profile_images/5193...",
      "username":"stuarthalloway"
     },
     {
      "screenname":"aalmiray",
      "influence":1023,
      "date":"2010-08-10",
      "tweet":"New weekly podcast series airs today @ d...",
      "tweetid":20812977124,
      "picture":"http://a3.twimg.com/profile_images/584l...",
      "username":"Andres Almiray"
     },
     {
      "screenname":"wakaleo",
      "influence":1020,
      "date":"2010-09-28",
      "tweet":"new article published: \"MongoDB: A NoSl...",
      "tweetid":25796403122,
      "picture":"http://a2.twimg.com/profile_images/116...",
      "username":"John Ferguson Smart"
      }
     ]
}

Accordingly, various JavaScript calls on web pages can retrieve this data, parse it (easily) and display it — for example, via JQuery‘s getJSON method. And by encapsulating how objects represent themselves as JSON, I don’t have to do too much JSON hand coding in various Servlets.