Working with JSON

Many AJAX application developers have adopted JSON as the data format of choice for server communication. It is a relatively simple format based on the object-literal notation of JavaScript. If you choose to use JSON-encoded data within your application, GWT contains classes you can use to parse and manipulate JSON objects.

JSON encoding

The JSON format is based on the syntax and data types of the JavaScript language. It supports strings, numbers, booleans, and null values. You can also combine multiple values into arrays and objects. JSON objects are simply unordered sets of name/value pairs, where the name is always a string and the value is any other valid JSON type (even another object). Here's an example of encoding product data in JSON:

{
  "product": {
    "name": "Widget",
    "company": "ACME, Inc",
    "partNumber": "7402-129",
    "prices": [
      { "minQty": 1, "price": 12.49 },
      { "minQty": 10, "price": 9.99 },
      { "minQty": 50, "price": 7.99 }
    ]
  }
}

See json.org/example.html for more JSON examples.

Parsing JSON

GWT's JSON types are contained in a separate module, so you'll need to add the necessary <inherits> tag to your module XML file:

<inherits name="com.google.gwt.json.JSON" />

Typically, you will receive JSON data as the response text of an HTTP request. Thus, you'll first have to convert that String into a data structure you can navigate and manipulate. GWT includes the JSONParser class to handle that transformation. Its lone static method parse(String) will accept the JSON text and parses is into a set of JSONValue-derived objects.

JSONValue is the superclass of all JSON types. Each of the basic JSON types is represented by a class in the com.google.gwt.json.client package. JSONValue contains a series of methods you can use to determine which specific subtype the value represents, and if possible perform the conversion. For example, the isBoolean() method will return a JSONBoolean if the JSONValue is really a JSONBoolean, or null if it is not.

Composite JSON types contain specialized methods for accessing their members. JSONObject has get(String) and put(String, JSONValue) methods for getting and setting the object's properties. JSONArray has corresponding methods named get(int) and set(int, JSONValue).

For a complete example of parsing JSON, see the JSON article in the Getting Started guide.

Mashups with JSON and JSNI

If you're loading JSON-encoded data from your own server, you'll typically use the RequestBuilder and related classes to make HTTP requests. However, you can also retrieve JSON from remote servers in true mashup fashion using GWT's JavaScript Native Interface (JSNI) functionality. The techniques for cross-site JSON is explained more fully in this FAQ article. To see a working example, check out the JSON/HTTP chapter in the Getting Started guide.