Gson JsonReader

Learn to work with Gson JsonReader class which is a pull-based streaming JSON parser. It helps in reading a JSON as a stream of tokens.

1. JsonReader

  • The JsonReader is the streaming JSON parser and an example of pull parser. A push parser parses through the JSON tokens and pushes them into an event handler.
  • It helps read a JSON (RFC 7159) encoded value as a stream of tokens.
  • It reads both literal values (strings, numbers, booleans, and nulls) as well as the begin and end delimiters of objects and arrays.
  • The tokens are traversed in depth-first order, the same order that they appear in the JSON document.

Read More : Streaming parser of XML

2. Tokens

In streaming mode, every JSON data is considered an individual token. When we use JsonReader to process it, each token will be processed sequentially. For example,


While parsing with JsonReader, above JSON will generate 4 tokens:

  • Token 1 = {
  • Token 2 = name
  • Token 3 = Lokesh
  • Token 4 = }

3. Create GSON JsonReader

We can create a JsonReader instance using its simple constructor which accepts type input stream.

String json = "{}";

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

We can use one of the following readers based on the source of JSON stream:

  • BufferedReader
  • LineNumberReader
  • CharArrayReader
  • InputStreamReader
  • FileReader
  • FilterReader
  • PushbackReader
  • PipedReader
  • StringReader

4. Read JSON Stream

After creating JsonReader wrapping a valid JSON source, we can start iterating over stream tokens and look into token values.

Following is an example of reading a simple JSON using JsonReader in the form of tokens.

public class Main 
  public static void main(String[] args) throws Exception 
    String json = "{'id': 1001,'firstName': 'Lokesh','lastName': 'Gupta','email': null}";
    JsonReader jsonReader = new JsonReader(new StringReader(json));
      while (jsonReader.hasNext()) 
        JsonToken nextToken = jsonReader.peek();
        if (JsonToken.BEGIN_OBJECT.equals(nextToken)) {
        } else if (JsonToken.NAME.equals(nextToken)) {
          String name = jsonReader.nextName();
          System.out.println("Token KEY >>>> " + name);
        } else if (JsonToken.STRING.equals(nextToken)) {
          String value = jsonReader.nextString();
          System.out.println("Token Value >>>> " + value);
        } else if (JsonToken.NUMBER.equals(nextToken)) {
          long value = jsonReader.nextLong();
          System.out.println("Token Value >>>> " + value);
        } else if (JsonToken.NULL.equals(nextToken)) {
          System.out.println("Token Value >>>> null");
        } else if (JsonToken.END_OBJECT.equals(nextToken)) {
    } catch (IOException e) {
    } finally {

The program output:

Token KEY >>>> id
Token Value >>>> 1001
Token KEY >>>> firstName
Token Value >>>> Lokesh
Token KEY >>>> lastName
Token Value >>>> Gupta
Token KEY >>>> email
Token Value >>>> null

In the above example:

  • The hasNext() method of the JsonReader returns true if it has more tokens.
  • The peek() method returns the next JSON token, but without moving over it.
  • Multiple calls to peek() will subsequently return the same JSON token.
  • The type of return token can be checked with constants of JsonToken class.
  • Array’s opening and closing brackets '[' and ']' are checked with beginArray() and endArray() methods.
  • Object’s opening and closing brackets '{' and '}' are checked with beginObject() and endObject() methods.

The key of the token is of type JsonToken.NAME. Use nextName() method to get the key name.

  • After determining the type of token, get the value of token using method like nextLong(), nextString(), nextInt() etc.
  • Null literals can be consumed using either nextNull() or skipValue().
  • All next....() method returns the value of the current token and moves the internal pointer to the next.
  • When an unknown name is encountered, strict parsers should fail with an exception. Lenient parsers should call skipValue() to recursively skip the value’s nested tokens, which may otherwise conflict.

Drop me your questions related to Gson JsonReader.

Happy Learning !!


Notify of
Inline Feedbacks
View all comments

About Us

HowToDoInJava provides tutorials and how-to guides on Java and related technologies.

It also shares the best practices, algorithms & solutions and frequently asked interview questions.