# The Java EE 7 Tutorial

# 19.4 Using the Streaming API

This section describes two use cases of the streaming API:

- Reading JSON data using a parser

- Writing JSON data using a generator

## 19.4.1 Reading JSON Data Using a Parser

The streaming API is the most efficient approach for parsing JSON text. The following code demonstrates how to create a `JsonParser` object and how to parse JSON data using events:

    import javax.json.Json;
    import javax.json.stream.JsonParser;
    ...
    JsonParser parser = Json.createParser(new StringReader(jsonData));
    while (parser.hasNext()) {
       JsonParser.Event event = parser.next();
       switch(event) {
          case START_ARRAY:
          case END_ARRAY:
          case START_OBJECT:
          case END_OBJECT:
          case VALUE_FALSE:
          case VALUE_NULL:
          case VALUE_TRUE:
             System.out.println(event.toString());
             break;
          case KEY_NAME:
             System.out.print(event.toString() + " " +
                              parser.getString() + " - ");
             break;
          case VALUE_STRING:
          case VALUE_NUMBER:
             System.out.println(event.toString() + " " +
                                parser.getString());
             break;
       }
    }

This example consists of three steps.

1. Obtain a parser instance by calling the `Json.createParser` static method.

2. Iterate over the parser events with the `JsonParser.hasNext` and the `JsonParser.next` methods.

3. Perform local processing for each element.

The example shows the ten possible event types from the parser. The parser's `next` method advances it to the next event. For the event types `KEY_NAME`, `VALUE_STRING`, and `VALUE_NUMBER`, you can obtain the content of the element by calling the method `JsonParser.getString`. For `VALUE_NUMBER` events, you can also use the following methods:

- `JsonParser.isIntegralNumber`

- `JsonParser.getInt`

- `JsonParser.getLong`

- `JsonParser.getBigDecimal`

See the Java EE 7 API reference for the `javax.json.stream.JsonParser` interface for more information.

The output of this example is the following:

    START_OBJECT
    KEY_NAME firstName - VALUE_STRING Duke
    KEY_NAME lastName - VALUE_STRING Java
    KEY_NAME age - VALUE_NUMBER 18
    KEY_NAME streetAddress - VALUE_STRING 100 Internet Dr
    KEY_NAME city - VALUE_STRING JavaTown
    KEY_NAME state - VALUE_STRING JA
    KEY_NAME postalCode - VALUE_STRING 12345
    KEY_NAME phoneNumbers - START_ARRAY
    START_OBJECT
    KEY_NAME type - VALUE_STRING mobile
    KEY_NAME number - VALUE_STRING 111-111-1111
    END_OBJECT
    START_OBJECT
    KEY_NAME type - VALUE_STRING home
    KEY_NAME number - VALUE_STRING 222-222-2222
    END_OBJECT
    END_ARRAY
    END_OBJECT

## 19.4.2 Writing JSON Data Using a Generator

The following code demonstrates how to write JSON data to a file using the streaming API:

    FileWriter writer = new FileWriter("test.txt");
    JsonGenerator gen = Json.createGenerator(writer);
    gen.writeStartObject()
       .write("firstName", "Duke")
       .write("lastName", "Java")
       .write("age", 18)
       .write("streetAddress", "100 Internet Dr")
       .write("city", "JavaTown")
       .write("state", "JA")
       .write("postalCode", "12345")
       .writeStartArray("phoneNumbers")
          .writeStartObject()
             .write("type", "mobile")
             .write("number", "111-111-1111")
          .writeEnd()
          .writeStartObject()
             .write("type", "home")
             .write("number", "222-222-2222")
          .writeEnd()
       .writeEnd()
    .writeEnd();
    gen.close();

This example obtains a JSON generator by calling the `Json.createGenerator` static method, which takes a writer or an output stream as a parameter. The example writes JSON data to the `test.txt` file by nesting calls to the `write`, `writeStartArray`, `writeStartObject`, and `writeEnd` methods. The `JsonGenerator.close` method closes the underlying writer or output stream.