type=page
status=published
title=Using the Streaming API
next=jsonp005.html
prev=jsonp003.html
~~~~~~
=Using the Streaming API


[[BABDBHIA]]

[[using-the-streaming-api]]
Using the Streaming API
-----------------------

This section describes two use cases of the streaming API.

The following topics are addressed here:

* link:#BABGCHIG[Reading JSON Data Using a Parser]
* link:#BABGJEEF[Writing JSON Data Using a Generator]

[[BABGCHIG]]

[[reading-json-data-using-a-parser]]
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:

[source,oac_no_warn]
----
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 API reference for the `javax.json.stream.JsonParser`
interface for more information.

The output of this example is the following:

[source,oac_no_warn]
----
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
----

[[BABGJEEF]]

[[writing-json-data-using-a-generator]]
Writing JSON Data Using a Generator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

[source,oac_no_warn]
----
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.


