Jackson Streaming API
External
- Parse JSON to Java using Streaming Jackson Parser http://www.studytrails.com/java/json/java-jackson-json-streaming/
- Streaming API 2.8 Javadoc http://fasterxml.github.io/jackson-core/javadoc/2.8/
Internal
Overview
The Streaming API reads and writes JSON as a series of discrete events, in a mode called "incremental parsing/generation". The concepts behind the Streaming API are similar to those of StAX. The Streaming API has the lowest overhead and its the fastest of all methods. The other two methods (Tree Model and Data Binding) are built in top of it. However, this is not the most convenient method, because is relatively low level. All content to read or write has to be processed in the order the input comes or the output has to go out. Random access is not possible. Also, no Java objects are created, unless specifically requested, and even then only very basic types are supported: String and byte[].
The central elements of the Streaming API are the parsers (org.codehaus.jackson.JsonParser) that are used for reading JSON content, and the generators (org.codehaus.jackson.JsonGenerator) that are used for writing Java state out as JSON.
JSON to Java - JSON Parsing with Streaming API
JSON content is parsed with a parser (org.codehaus.jackson.JsonParser).
JsonParser instances are created using factory methods of a JsonFactory instance. Once created, they are invoked in a loop, and they identify JsonTokens in the input content until the end of content is reached.
According to the documentation, nextToken() is the main iteration method, which will advance stream enough to determine type of the next token, if any. Upon completion, the method will return a JsonToken instance identifying the token that has just been identified.
JsonToken token = parser.nextToken();
JsonToken is an enumeration, which describe all possible types of tokens identified by the parser.
Once the parser identified a token, the value associated with the token can be retrieved, as String, with JsonParser.getText() and can be interpreted according to the token type. For tokens whose type is more specific, we can alternatively use more specialized methods JsonParser.getIntValue(), JsonParser.getFloatValue(), etc. If the token is JsonToken.FIELD_NAME, getText() returns the name of the field.
JsonToken can be:
- START_OBJECT - returned when encountering '{' which signals starting of an Object value.
- END_OBJECT - returned when encountering '}' which signals ending of an Object value
- START_ARRAY - returned when encountering '[' which signals starting of an Array value
- END_ARRAY - returned when encountering ']' which signals ending of an Array value
- FIELD_NAME - returned when a String token is encountered as a field name (same lexical value, different function)
- VALUE_NULL - returned when encountering literal "null" in value context
- VALUE_TRUE - returned when encountering literal "true" in value context
- VALUE_FALSE - returned when encountering literal "false" in value context
- VALUE_NUMBER_INT - returned when an integer numeric token is encountered in value context: that is, a number that does not have floating point or exponent marker in it. It consists only of an optional sign, followed by one or more digits.
- VALUE_NUMBER_FLOAT - returned when a numeric token other that is not an integer is encountered: that is, a number that does have floating point or exponent marker in it, in addition to one or more digits.
- VALUE_STRING - returned when a String token is encountered in value context (array element, field value, or root-level stand-alone value)
- NOT_AVAILABLE can be returned if JsonParser implementation can not currently return the requested token (usually next one), or even if any will be available, but that may be able to determine this in future.
- VALUE_EMBEDDED_OBJECT - placeholder token returned when the input source has a concept of embedded Object that are not accessible as usual structure (of starting with START_OBJECT, having values, ending with END_OBJECT), but as "raw" objects.
JSON Parsing with Streaming API Code Example
Java to JSON - Writing Java State as JSON with Streaming API
Java state is written as JSON using a generator (org.codehaus.jackson.JsonGenerator):
ByteArrayOutputStream destination = new ByteArrayOutputStream();
JsonFactory f = new JsonFactory();
JsonGenerator generator = f.createGenerator(destination);
generator.writeStartObject();
generator.writeFieldName("test-field-name");
generator.writeString("test-field-value");
generator.writeEndObject();
generator.close();