JavaScript Object Notation (JSON)

Introduction

JSON is a simple, text-based way of marshaling object data. Objects are represented by collections of key/value pairs (a.k.a hashes). Values can be any of the following types: number, string, boolean (true or false), null, object or array. Arrays are collections of values. The syntax is described here.

There are libraries available for many programming languages that marshal objects to JSON strings and unmarshal JSON strings to objects. A list of these can be found near the bottom of this page.

Example

This example will demonstrate using the Java library Json-lib. It relies on the following additional libraries.

• Jakarta Commons Beanutils
• Jakarta Commons Lang
• Jakarta Commons Logging
• Ezmorph
• JUnit

The data in this example represents musical artists, their recordings, and tracks on those recordings. There is a Java Bean class for each of these kinds of data named Artist, Recording and Track.

The example is built and run using Ant. For details, see build.properties and build.xml.

A few utility classes were written to simplify the code. These include ObjectUtil, SystemUtil and JSONUtil.

Once armed with the preceding code, using JSON can be as simple as the following code implemented as a JUnit 4 test case.

package com.ociweb.demo;

import com.ociweb.json.*;
import java.util.*;
import org.junit.*;

import static com.ociweb.lang.SystemUtil.*;
import static org.junit.Assert.*;

public class JSONUtilTest {

  private JSONUtil jsonUtil = new JSONUtil();

  @Before public void setup() {
    // Whenever a key in a JSON object is "recordings",
    // tread the value as an array of Recording objects.
    jsonUtil.addMapping("recordings", Recording.class);
  }

  /**
   * This tests converting a object to JSON when the object
   * has a field that holds a collection of references to other objects.
   */
  @Test public void testObjectConvert() {
    Artist a = new Artist("Regina Spektor");
    a.addRecording("Soviet Kitch", 2003);
    a.addRecording("Begin To Hope", 2006);

    Object expected = a;
    String json = jsonUtil.toJSON(expected);
    Object actual = jsonUtil.fromJSONObject(json, Artist.class);
    assertEquals(expected, actual);
  }

  /**
   * This tests converting an array of objects to JSON when the objects
   * have a field that holds a collection of references to other objects.
   */
  @Test public void testArrayConvert() {
    List<Artist> artists = new ArrayList<Artist>();

    Artist a = new Artist("Deathcab For Cutie");
    artists.add(a);
    Recording r =
      a.addRecording("We Have the Facts and We're Voting Yes", 2000);
    a.addRecording("The Photo Album", 2001);
    a.addRecording("You Can Play These Songs With Chords", 2002);
    a.addRecording("Transatlanticism", 2003);
    a.addRecording("Plans", 2005);

    a = new Artist("Regina Spektor");
    artists.add(a);
    r = a.addRecording("Begin To Hope", 2006);
    
    r.addTrack("20 Years Of Snow", 4);
    r = a.addRecording("Soviet Kitch", 2003);
    r.addTrack("Chemo Limo", 4);
    r.addTrack("Somedays", 5);

    Object[] expected = artists.toArray();
    String json = jsonUtil.toJSON(expected);
    Object[] actual = jsonUtil.fromJSONArray(json, Artist.class);
    assertEquals(expected, actual);
  }

  /**
   * This tests converting a collection to JSON.
   */
  @Test public void testCollectionConvert() {
    List<String> colors = new ArrayList<String>();
    colors.add("red");
    colors.add("green");
    colors.add("blue");

    List<String> expected = colors;
    String json = jsonUtil.toJSON(expected);
    List actual = jsonUtil.fromJSONList(json, String.class);
    assertEquals(expected, actual);
  }
}

Copyright © 2007 Object Computing, Inc. All rights reserved.