The first article I wrote about GSON (part 1) is (at the time of writing) the most popular article in my small blog. Thus, I decided to write a second article and add more practical and advance examples which anyone can use. As also noted in my previous article, the official GSON site is: http://sites.google.com/site/gson/.
In this article we will see how to parse complex JSON objects into existing Java objects that do not necessary have the same structure as the JSON object. We will see how the use of the GSON deserialiser (JsonDeserializer) in order to control how the JSON object maps to the Java object.
The code shown here is all available at: http://code.google.com/p/gson-practical-examples/source/checkout.
The readers are encouraged to first read part 1 before proceeding, unless they are already familiar with GSON.
A Simple Example
Let's say we have the following JSON object, where it contains four Java books titles written by various, well known, authors.
{
'1': 'Effective Java (2nd Edition)',
'2': 'JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases',
'3': 'Java Concurrency in Practice',
'4': 'Java: The Good Parts'
}
Note that each name/value pair has a number as its name and the book title as its value. Using the methods discussed in part 1 would create a problem. In that article, Gson is expecting to find variable names in Java with the same name as that found in JSON. But names in Java cannot start with a number. They can contain a number, but cannot start with one (as described in chapter 6 of the Java Language Specification).
So how can we parse this JSON object and use it in Java?
We can use the JsonDeserializer to parse the JSON object into our Java object the way we want it. Using the JsonDeserializer, we have full control over how JSON is parsed as we will see in the following example.
Consider the following simple Java object.
package com.albertattard.examples.gson.part2_1;
import java.util.ArrayList;
import java.util.List;
public class Books {
private List<string> booksTitles = new ArrayList<>();
public void addBookTitle(String title) {
booksTitles.add(title);
}
@Override
public String toString() {
return booksTitles.toString();
}
}
This Java object will be used to hold the books listed in the JSON object shown earlier. Note that JSON object has four fields, one for each book, while the Java object has a list in which these books are saved. The structure of these two objects (Java and JSON) is different.
In order to be able to parse JSON to Java we need to create our own instance of the JsonDeserializer interface as shown next.
package com.albertattard.examples.gson.part2_1;
import java.lang.reflect.Type;
import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonParseException;
public class BooksDeserializer implements JsonDeserializer<Books> {
@Override
public Books deserialize(final JsonElement json,
final Type typeOfT,
final JsonDeserializationContext context)
throws JsonParseException {
Books books = new Books();
// Parsing will be done here.
return books;
}
}
The above example is not complete and we still need to add the most important thing, which is the parsing. But let's understand this class before we make it more complex by adding more code to it. The interface JsonDeserializer requires a type, which is the type of object that we will be parsing. In this case, we are parsing JSON into the Java object of type Books. The return type of the deserialize() method must be of the same type as the interface parameter, Books.
How does this work?
Gson will parse the JSON object into a Java object of type JsonElement. The JsonElement can be thought of a tree of name/value pairs containing all elements found in the JSON object. Each child within the JsonElement is yet another JsonElement. In other words we have a tree of JsonElements. Through this object we can retrieve each JSON element by its name and set the Java object accordingly. The following example shows how we can retrieve the first book listed in the JSON object and add it to the Java object.
package com.albertattard.examples.gson.part2_1;
import java.lang.reflect.Type;
import com.google.gson.JsonDeserializationContext;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParseException;
public class BooksDeserializer implements JsonDeserializer<Books> {
@Override
public Books deserialize(final JsonElement json,
final Type typeOfT,
final JsonDeserializationContext context)
throws JsonParseException {
Books books = new Books();
JsonObject jsonObject = json.getAsJsonObject();
books.addBookTitle(jsonObject.get("1").getAsString());
return books;
}
}
"1" using the following code fragment:
jsonObject.get("1")
JsonElement with the name: "1". In this case it is a simple String. Note that in order to retrieve the actual value we need to invoke another method on the JsonElement instance, which returns the value we need, String in this case.
jsonObject.get("1").getAsString()
The rest of the books titles can be retrieved in the same manner.
Before we can utilise our new deserializer, we must instruct GSON to use our deserializer when parsing objects of type Books, as shown in the next code example.
package com.albertattard.examples.gson.part2_1;
import java.io.InputStreamReader;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class Main {
public static void main(String[] args) throws Exception {
// Configure GSON
GsonBuilder gsonBuilder = new GsonBuilder();
gsonBuilder.registerTypeAdapter(Books.class,
new BooksDeserializer());
Gson gson = gsonBuilder.create();
// The JSON data
Reader data = new InputStreamReader(
Main.class.getResourceAsStream("books.json"), "UTF-8");
// Parse JSON to Java
Books books = gson.fromJson(data, Books.class);
System.out.println(books);
}
}
Gson through the GsonBuilder. Using the registerTypeAdapter() method, we are registering our deserializer and instructing GSON to use our deserializer when deserializing objects of type Books. When we request GSON to deserialize an object to the Books class, GSON will use our deserializer . The following list describes what happens when we invoke: gson.fromJson(data, Books.class).- Parse the input as
JsonElement. At this stage, the string JSON object is changed into a generic Java object of typeJsonElement. This step also ensures that the given JSON data is valid. - Find the deserializer for the given object, in this case the
BooksDeserializerinstance. - Invokes the method
deserialize()and provides the necessary parameters. In his example, ourdeserialize()will be invoked. Here an object of typeBooksis created from the givenJsonElementobject. This is from Java to Java conversion. - Returns the object returned by the
deserialize()method to the caller of thefromJson()method. This is like a chain, where GSON receives an object from out deserializer and returns it to its caller.
[Effective Java (2nd Edition), JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases, Java Concurrency in Practice, Java: The Good Parts]
This concludes our simple example. This example acts as a primer for other complex parsing. For example, parsing JSON objects that include nested objects, arrays and the like. In the next example we will discuss an enhanced version of the objects discussed here.
Nested Objects
In this example we will describe how to parse nested objects, that is, objects within other objects. Here we will introduce a new entity, the author. A book, together with the title and ISBN can have a list of authors. On the other hand every author can have many books. The JSON object that will be using in this example differs from the previous one to cater for the new entity as shown next:
{
'1': {
'title': 'Effective Java (2nd Edition)',
'isbn': '978-0321356680',
'authors': ['Joshua Bloch']
},
'2': {
'title': 'JavaTM Puzzlers: Traps, Pitfalls, and Corner Cases',
'isbn': '978-0321336781',
'authors': ['Joshua Bloch', 'Neal Gafter']
},
'3': {
'title': 'Java Concurrency in Practice',
'isbn': '978-0321349606',
'authors': ['Brian Goetz', 'Tim Peierls', 'Joshua Bloch',
'Joseph Bowbeer', 'David Holmes', 'Doug Lea']
},
'4': {
'title': 'Java: The Good Parts',
'isbn': '978-0596803735',
'authors': ['Jim Waldo']
}
}
The new example provides new challenges. One of the authors, Joshua Bloch, has three books. This immediately leads to the following question.
How many instance of this author should we have?
There are two possible answers for this question: just one or three (one for every book). There is no one correct answer, and both cases can be valid. In our examples we are going to have one instance of the author even when he or she has more than one book. We are taking this approach as this approach resembles the reality and helps highlighting the goal of this article (GSON examples). Therefore we will have one author object representing the author Joshua Bloch.
For this example we will be using three domain objects:
- Author
- Book
- Books
Author class has a list of Books and the Book has a list of Authors. The Books class contains all parsed objects. The Books class also provides the functionality required to maintain one instance for each author as we will see later on in this example.Author
package com.albertattard.examples.gson.part2_2;
import java.util.HashSet;
import java.util.Set;
public class Author {
private Set<Book> books = new HashSet<>();
private String name;
public Author(final String name) {
this.name = name;
}
public void addBook(Book book) {
books.add(book);
}
public Set<Book> getBooks() {
return books;
}
public String getName() {
return name;
}
@Override
public String toString() {
return String.format("%s has %d book(s)", name, books.size());
}
}
Book
package com.albertattard.examples.gson.part2_2;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
public class Book {
private Set<Author> authors;
private String isbn;
private String title;
public Book(String title, String isbn, Author... authors) {
this.title = title;
this.isbn = isbn;
this.authors = new HashSet<>(Arrays.asList(authors));
}
public Set<Author> getAuthors() {
return authors;
}
@Override
public String toString() {
StringBuilder fomrattedString = new StringBuilder();
fomrattedString.append(title).append(" (").append(isbn)
.append(")");
fomrattedString.append(" by: ");
for (Author author : authors) {
fomrattedString.append(author.getName()).append(", ");
}
// To remove the last comma followed by a space
return fomrattedString.
substring(0, fomrattedString.length() - 2);
}
}
Books
package com.albertattard.examples.gson.part2_2;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
public class Books {
// A map of authors index by their name.
private Map<String, Author> authors = new HashMap<>();
private Set<Book> books = new HashSet<>();
public void addAuthor(Author author) {
authors.put(author.getName(), author);
}
public void addBook(Book book) {
books.add(book);
}
public Author getAuthorWithName(String name) {
return authors.get(name);
}
@Override
public String toString() {
StringBuilder formattedString = new StringBuilder();
for (Author author : authors.values()) {
formattedString.append(author).append("\n");
for (Book book : author.getBooks()) {
formattedString.append(" ").append(book).append("\n");
}
formattedString.append("\n");
}
return formattedString.toString();
}
}
Coming soon.
This article is not complete and more information will follow shortly.
Thanks for your article. I often find myself in the situation of having a JSON object to parse without having the control of it's creation/format. Surprisingly it's not a well documented case regardless of the library (Gson, Jackson ...)
ReplyDelete