GSON - JsonReader

Jakob Jenkov
Last update: 2016-02-18

The GSON JsonReader is the GSON streaming JSON parser. The GSON JsonReader enables you to read a JSON string or file as a stream of JSON tokens.

Iterating JSON token for token is also referred to as streaming through the JSON tokens. That is why the GSON JsonReader is also sometimes referred to as a streaming JSON parser.

Streaming parsers typically come in two versions: Pull parsers and push parsers. A pull parser is a parser where the code using it pulls the tokens out of the parser when the code is ready to handle the next token. A push parser parses through the JSON tokens and pushes them into an event handler. The GSON JsonReader is a pull parser.

In this GSON JsonReader tutorial we will take a closer look at what that means, and how the JsonReader works.

Creating a GSON JsonReader

You create a GSON JsonReader like this:

String json = "{\"brand\" : \"Toyota\", \"doors\" : 5}";

JsonReader jsonReader = new JsonReader(new StringReader(json));

Notice how the JsonReader constructor takes a Java Reader as parameter. In the example above we pass a Java StringReader to the JsonReader's constructor. The StringReader is capable of "converting" a Java string into a character stream (a Reader in other words).

Iterating the JSON Tokens of a JsonReader

Once you have created a JsonReader instance you can iterate through the JSON tokens it reads from the Reader passed to the JsonReader's constructor.

The main look for iterating the JSON tokens of a JsonReader looks like this:

while(jsonReader.hasNext() {


The hasNext() method of the JsonReader returns true if the JsonReader has more tokens.

To access the tokens of the JsonReader you use a loop similar to the following:

String json = "{\"brand\" : \"Toyota\", \"doors\" : 5}";

JsonReader jsonReader = new JsonReader(new StringReader(json));

try {
        JsonToken nextToken = jsonReader.peek();



        } else if(JsonToken.NAME.equals(nextToken)){

            String name  =  jsonReader.nextName();

        } else if(JsonToken.STRING.equals(nextToken)){

            String value =  jsonReader.nextString();

        } else if(JsonToken.NUMBER.equals(nextToken)){

            long value =  jsonReader.nextLong();

} catch (IOException e) {

The JsonReader peek() method returns the next JSON token, but without moving over it. Multiple calls to peek() subsequently will return the same JSON token.

The JsonToken returned by peek() can be compared to constants in the JsonToken class to find out what type of token it is. You can see that done in the loop above.

Inside each if statement a JsonReader method is called which moves the JsonReader over the current token, and on to the next token. All of beginObject(), nextString() and nextLong() return the value of the current token and moves the internal pointer to the next.

Jakob Jenkov

Featured Videos

Java ForkJoinPool

P2P Networks Introduction


Java Persistence
Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Next tutorial in this tutorial trail