GSON is a Java API, developed by Google, used to convert between Java objects and JSON objects. This article discusses and provides examples about this API and how it can be used. More information about this API can be found at: http://sites.google.com/site/gson/.
This is the first from three articles about GSON. No GSON or JSON experience is required as this article acts as a primer for the other two articles. The second article provides more examples about the use of GSON deserializer (from JSON to Java) and the third and final article provides more examples about the GSON serializer (from Java to JSON). All code for all three articles is available at: http://code.google.com/p/gson-practical-examples/source/checkout.
Download and Install
Before you can do any work with this API, you need to download the library (jar file) and include it in the classpath. The library, together with the source and JavaDocs, can be downloaded from: http://code.google.com/p/google-gson/downloads/list. Once downloaded, add thegson-<version>.jar to the classpath. For those readers who prefer to use maven to manage the dependencies (JAR files), add the following dependency to the pom.xml.
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.2.1</version>
</dependency>
<version>2.2.1</version> as required. All code examples shown in this article use the version listed above. A copy of the pom.xml file can be found here.If this library is to be used in a web application, make sure to have a copy saved under the WEB-INF/lib folder. Alternatively, the library can be added to the application server and made available to the web application.
A Simple Example
The GSON API provides a stateless class,Gson, that handles the conversions between Java and JSON objects. An instance of this class can be created by invoking the default constructor or as shown in the simple example below, using the GsonBuilder class. The GsonBuilder class provides customisation and allows the developer to instantiate Gson as required.
package com.albertattard.examples.gson.part1_1;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class SimpleExample1 {
public static void main(String[] args) {
Gson gson = new GsonBuilder().create();
gson.toJson("Hello", System.out);
gson.toJson(123, System.out);
}
}
Gson and converted the Java String and int to JSON objects. The above code produces the following as its output to the command prompt: "Hello"123toJason() method takes two parameters, the Java object to be converted to JSON and an instance of Appendable. We can easily change the out to a file or network stream.
package com.albertattard.examples.gson.part1_1;
import java.io.FileWriter;
import java.io.IOException;
import java.io.Writer;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class SimpleExample2 {
public static void main(String[] args) throws IOException {
Writer writer = new FileWriter("Output.json");
Gson gson = new GsonBuilder().create();
gson.toJson("Hello", writer);
gson.toJson(123, writer);
writer.close();
}
}
Writer when the actual type is FileWriter? It is a good practice to have your variables as generic as possible. In the above example, we're only using methods defined by the
Appendable and Writer interfaces. Having the variable type more specific than required will make the code less portable and harder to maintain as we'll see in the following example.Note that in the above example we are not handling the steams (Writer) properly. Ideally the resources are closed within the finally block or used within the try-with-resources as shown below. We've ignored this to keep the code as simple as possible.
public static void main(String[] args) throws IOException {
try (Writer writer = new FileWriter("Output.json")) {
Gson gson = new GsonBuilder().create();
gson.toJson("Hello", writer);
gson.toJson(123, writer);
}
}
The above code produces the file: Output.json with the JSON objects. Note that here we used the character streams and not the byte streams. We cannot use the byte streams as the toJson() method is expecting an Appendable instance and the byte streams are not descendants from the Appendable interface. The Appendable interface works with characters and not bytes. Java provides the InputStreamReader and the OutputStreamWriter classes that convert byte streams into character streams as illustrated in the following example.
package com.albertattard.examples.gson.part1_1;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class SimpleExample3 {
public static void main(String[] args) throws IOException {
Writer writer = new OutputStreamWriter(
new FileOutputStream("Output.json"));
Gson gson = new GsonBuilder().create();
gson.toJson("Hello", writer);
gson.toJson(123, writer);
writer.close();
}
}
Consuming JSON objects
Let's say that we need to consume JSON objects and load them as Java objects. Assume that a web server will produce the following JSON when queried:
{
NAME:"Albert Attard",
P_LANGUAGE:"Java",
LOCATION:"Malta"
}
First we need to create a Java class with the fields that we want to represent (name and location). Let's call the class Person1. The name of this class is irrelevant, but the name of the fields is not. The field names must match (including the case) with the names in JSON. Also, the class must include a default constructor. As shown below, the fields name and location are in uppercase as found in JSON. The JSON field P_LANGUAGE is ignored as the Java object does not include a field with this name. It is understandable that the fields' names do not follow the Java naming convention, but for the time being let's keep things simple. More about this is discussed in part 2.
package com.albertattard.examples.gson.part1_2;
public class Person1 {
private String NAME;
private String LOCATION;
// Getters and setters are not required for this example.
// GSON sets the fields directly.
@Override
public String toString() {
return NAME + " - " + LOCATION;
}
}
package com.albertattard.examples.gson.part1_2;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.Reader;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class JsonToJava1 {
public static void main(String[] args) throws IOException {
Reader reader = new InputStreamReader(JsonToJava1.class
.getResourceAsStream("Server1.json"));
Gson gson = new GsonBuilder().create();
Person1 p = gson.fromJson(reader, Person1.class);
System.out.println(p);
reader.close();
}
}
Albert Attard - Malta. Gson parsed the JSON object and created an instance of the Person1 class. Nested JSON Objects
Let's take the above example one step further and include a nested object as illustrated in the following JSON code fragment.
{
NAME:"Albert Attard",
P_LANGUAGE:"Java",
LOCATION:"Malta",
EXAM: {
SUBJECT:"Programming",
GRADE:4.5
}
}
EXAM field which is made from two other fields: SUBJECT and GRADE. Likewise, we need to modify the Person1 class defined above to include the EXAM field and create a new Java class to represent the SUBJECT and GRADE fields. We first create the new class that will represent the nested object. As we discussed before, the class name is irrelevant but the fields' names must match those define in JSON.
package com.albertattard.examples.gson.part1_3;
public class Exam1 {
private String SUBJECT;
private double GRADE;
// Getters and setters are not required for this example.
// GSON sets the fields directly.
@Override
public String toString() {
return SUBJECT + " - " + GRADE;
}
}
Person1 class (Person2 in the following example) and include a new field with the same name as in JSON of type Exam1 as shown next. Instead we created a new class to keep track of the progress made.
package com.albertattard.examples.gson.part1_3;
public class Person2 {
private String NAME;
private String LOCATION;
private Exam1 EXAM;
@Override
public String toString() {
return NAME + " - " + LOCATION + " (" + EXAM + ")";
}
}
Finally, let's test the new changes.
package com.albertattard.examples.gson.part1_3;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.Reader;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
public class JsonToJava2 {
public static void main(String[] args) throws IOException {
Reader reader = new InputStreamReader(JsonToJava2.class
.getResourceAsStream("Server2.json"));
Gson gson = new GsonBuilder().create();
Person2 p = gson.fromJson(reader, Person2.class);
System.out.println(p);
reader.close();
}
}
Conclusion
Even though it may be a new concept, JSON is very simple and straight forward. The Gson API makes it very simple to use and even though not discussed here, it provides a great deal of flexibility.For more GSON examples please visit the second part (part-2), where we explore more complex examples and discuss how to use the GSON deserializer to take full control over the deserialization process.
