530 lines
16 KiB
Java
530 lines
16 KiB
Java
/*
|
|
* Copyright (C) 2010 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package android.util;
|
|
|
|
import java.io.Closeable;
|
|
import java.io.IOException;
|
|
import java.io.Writer;
|
|
import java.util.ArrayList;
|
|
import java.util.List;
|
|
|
|
/**
|
|
* Writes a JSON (<a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>)
|
|
* encoded value to a stream, one token at a time. The stream includes both
|
|
* literal values (strings, numbers, booleans and nulls) as well as the begin
|
|
* and end delimiters of objects and arrays.
|
|
*
|
|
* <h3>Encoding JSON</h3>
|
|
* To encode your data as JSON, create a new {@code JsonWriter}. Each JSON
|
|
* document must contain one top-level array or object. Call methods on the
|
|
* writer as you walk the structure's contents, nesting arrays and objects as
|
|
* necessary:
|
|
* <ul>
|
|
* <li>To write <strong>arrays</strong>, first call {@link #beginArray()}.
|
|
* Write each of the array's elements with the appropriate {@link #value}
|
|
* methods or by nesting other arrays and objects. Finally close the array
|
|
* using {@link #endArray()}.
|
|
* <li>To write <strong>objects</strong>, first call {@link #beginObject()}.
|
|
* Write each of the object's properties by alternating calls to
|
|
* {@link #name} with the property's value. Write property values with the
|
|
* appropriate {@link #value} method or by nesting other objects or arrays.
|
|
* Finally close the object using {@link #endObject()}.
|
|
* </ul>
|
|
*
|
|
* <h3>Example</h3>
|
|
* Suppose we'd like to encode a stream of messages such as the following: <pre> {@code
|
|
* [
|
|
* {
|
|
* "id": 912345678901,
|
|
* "text": "How do I write JSON on Android?",
|
|
* "geo": null,
|
|
* "user": {
|
|
* "name": "android_newb",
|
|
* "followers_count": 41
|
|
* }
|
|
* },
|
|
* {
|
|
* "id": 912345678902,
|
|
* "text": "@android_newb just use android.util.JsonWriter!",
|
|
* "geo": [50.454722, -104.606667],
|
|
* "user": {
|
|
* "name": "jesse",
|
|
* "followers_count": 2
|
|
* }
|
|
* }
|
|
* ]}</pre>
|
|
* This code encodes the above structure: <pre> {@code
|
|
* public void writeJsonStream(OutputStream out, List<Message> messages) throws IOException {
|
|
* JsonWriter writer = new JsonWriter(new OutputStreamWriter(out, "UTF-8"));
|
|
* writer.setIndent(" ");
|
|
* writeMessagesArray(writer, messages);
|
|
* writer.close();
|
|
* }
|
|
*
|
|
* public void writeMessagesArray(JsonWriter writer, List<Message> messages) throws IOException {
|
|
* writer.beginArray();
|
|
* for (Message message : messages) {
|
|
* writeMessage(writer, message);
|
|
* }
|
|
* writer.endArray();
|
|
* }
|
|
*
|
|
* public void writeMessage(JsonWriter writer, Message message) throws IOException {
|
|
* writer.beginObject();
|
|
* writer.name("id").value(message.getId());
|
|
* writer.name("text").value(message.getText());
|
|
* if (message.getGeo() != null) {
|
|
* writer.name("geo");
|
|
* writeDoublesArray(writer, message.getGeo());
|
|
* } else {
|
|
* writer.name("geo").nullValue();
|
|
* }
|
|
* writer.name("user");
|
|
* writeUser(writer, message.getUser());
|
|
* writer.endObject();
|
|
* }
|
|
*
|
|
* public void writeUser(JsonWriter writer, User user) throws IOException {
|
|
* writer.beginObject();
|
|
* writer.name("name").value(user.getName());
|
|
* writer.name("followers_count").value(user.getFollowersCount());
|
|
* writer.endObject();
|
|
* }
|
|
*
|
|
* public void writeDoublesArray(JsonWriter writer, List<Double> doubles) throws IOException {
|
|
* writer.beginArray();
|
|
* for (Double value : doubles) {
|
|
* writer.value(value);
|
|
* }
|
|
* writer.endArray();
|
|
* }}</pre>
|
|
*
|
|
* <p>Each {@code JsonWriter} may be used to write a single JSON stream.
|
|
* Instances of this class are not thread safe. Calls that would result in a
|
|
* malformed JSON string will fail with an {@link IllegalStateException}.
|
|
*/
|
|
@android.ravenwood.annotation.RavenwoodKeepWholeClass
|
|
public final class JsonWriter implements Closeable {
|
|
|
|
/** The output data, containing at most one top-level array or object. */
|
|
private final Writer out;
|
|
|
|
private final List<JsonScope> stack = new ArrayList<JsonScope>();
|
|
{
|
|
stack.add(JsonScope.EMPTY_DOCUMENT);
|
|
}
|
|
|
|
/**
|
|
* A string containing a full set of spaces for a single level of
|
|
* indentation, or null for no pretty printing.
|
|
*/
|
|
private String indent;
|
|
|
|
/**
|
|
* The name/value separator; either ":" or ": ".
|
|
*/
|
|
private String separator = ":";
|
|
|
|
private boolean lenient;
|
|
|
|
/**
|
|
* Creates a new instance that writes a JSON-encoded stream to {@code out}.
|
|
* For best performance, ensure {@link Writer} is buffered; wrapping in
|
|
* {@link java.io.BufferedWriter BufferedWriter} if necessary.
|
|
*/
|
|
public JsonWriter(Writer out) {
|
|
if (out == null) {
|
|
throw new NullPointerException("out == null");
|
|
}
|
|
this.out = out;
|
|
}
|
|
|
|
/**
|
|
* Sets the indentation string to be repeated for each level of indentation
|
|
* in the encoded document. If {@code indent.isEmpty()} the encoded document
|
|
* will be compact. Otherwise the encoded document will be more
|
|
* human-readable.
|
|
*
|
|
* @param indent a string containing only whitespace.
|
|
*/
|
|
public void setIndent(String indent) {
|
|
if (indent.isEmpty()) {
|
|
this.indent = null;
|
|
this.separator = ":";
|
|
} else {
|
|
this.indent = indent;
|
|
this.separator = ": ";
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Configure this writer to relax its syntax rules. By default, this writer
|
|
* only emits well-formed JSON as specified by <a
|
|
* href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>. Setting the writer
|
|
* to lenient permits the following:
|
|
* <ul>
|
|
* <li>Top-level values of any type. With strict writing, the top-level
|
|
* value must be an object or an array.
|
|
* <li>Numbers may be {@link Double#isNaN() NaNs} or {@link
|
|
* Double#isInfinite() infinities}.
|
|
* </ul>
|
|
*/
|
|
public void setLenient(boolean lenient) {
|
|
this.lenient = lenient;
|
|
}
|
|
|
|
/**
|
|
* Returns true if this writer has relaxed syntax rules.
|
|
*/
|
|
public boolean isLenient() {
|
|
return lenient;
|
|
}
|
|
|
|
/**
|
|
* Begins encoding a new array. Each call to this method must be paired with
|
|
* a call to {@link #endArray}.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter beginArray() throws IOException {
|
|
return open(JsonScope.EMPTY_ARRAY, "[");
|
|
}
|
|
|
|
/**
|
|
* Ends encoding the current array.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter endArray() throws IOException {
|
|
return close(JsonScope.EMPTY_ARRAY, JsonScope.NONEMPTY_ARRAY, "]");
|
|
}
|
|
|
|
/**
|
|
* Begins encoding a new object. Each call to this method must be paired
|
|
* with a call to {@link #endObject}.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter beginObject() throws IOException {
|
|
return open(JsonScope.EMPTY_OBJECT, "{");
|
|
}
|
|
|
|
/**
|
|
* Ends encoding the current object.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter endObject() throws IOException {
|
|
return close(JsonScope.EMPTY_OBJECT, JsonScope.NONEMPTY_OBJECT, "}");
|
|
}
|
|
|
|
/**
|
|
* Enters a new scope by appending any necessary whitespace and the given
|
|
* bracket.
|
|
*/
|
|
private JsonWriter open(JsonScope empty, String openBracket) throws IOException {
|
|
beforeValue(true);
|
|
stack.add(empty);
|
|
out.write(openBracket);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Closes the current scope by appending any necessary whitespace and the
|
|
* given bracket.
|
|
*/
|
|
private JsonWriter close(JsonScope empty, JsonScope nonempty, String closeBracket)
|
|
throws IOException {
|
|
JsonScope context = peek();
|
|
if (context != nonempty && context != empty) {
|
|
throw new IllegalStateException("Nesting problem: " + stack);
|
|
}
|
|
|
|
stack.remove(stack.size() - 1);
|
|
if (context == nonempty) {
|
|
newline();
|
|
}
|
|
out.write(closeBracket);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Returns the value on the top of the stack.
|
|
*/
|
|
private JsonScope peek() {
|
|
return stack.get(stack.size() - 1);
|
|
}
|
|
|
|
/**
|
|
* Replace the value on the top of the stack with the given value.
|
|
*/
|
|
private void replaceTop(JsonScope topOfStack) {
|
|
stack.set(stack.size() - 1, topOfStack);
|
|
}
|
|
|
|
/**
|
|
* Encodes the property name.
|
|
*
|
|
* @param name the name of the forthcoming value. May not be null.
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter name(String name) throws IOException {
|
|
if (name == null) {
|
|
throw new NullPointerException("name == null");
|
|
}
|
|
beforeName();
|
|
string(name);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code value}.
|
|
*
|
|
* @param value the literal string value, or null to encode a null literal.
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter value(String value) throws IOException {
|
|
if (value == null) {
|
|
return nullValue();
|
|
}
|
|
beforeValue(false);
|
|
string(value);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code null}.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter nullValue() throws IOException {
|
|
beforeValue(false);
|
|
out.write("null");
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code value}.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter value(boolean value) throws IOException {
|
|
beforeValue(false);
|
|
out.write(value ? "true" : "false");
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code value}.
|
|
*
|
|
* @param value a finite value. May not be {@link Double#isNaN() NaNs} or
|
|
* {@link Double#isInfinite() infinities} unless this writer is lenient.
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter value(double value) throws IOException {
|
|
if (!lenient && (Double.isNaN(value) || Double.isInfinite(value))) {
|
|
throw new IllegalArgumentException("Numeric values must be finite, but was " + value);
|
|
}
|
|
beforeValue(false);
|
|
out.append(Double.toString(value));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code value}.
|
|
*
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter value(long value) throws IOException {
|
|
beforeValue(false);
|
|
out.write(Long.toString(value));
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Encodes {@code value}.
|
|
*
|
|
* @param value a finite value. May not be {@link Double#isNaN() NaNs} or
|
|
* {@link Double#isInfinite() infinities} unless this writer is lenient.
|
|
* @return this writer.
|
|
*/
|
|
public JsonWriter value(Number value) throws IOException {
|
|
if (value == null) {
|
|
return nullValue();
|
|
}
|
|
|
|
String string = value.toString();
|
|
if (!lenient &&
|
|
(string.equals("-Infinity") || string.equals("Infinity") || string.equals("NaN"))) {
|
|
throw new IllegalArgumentException("Numeric values must be finite, but was " + value);
|
|
}
|
|
beforeValue(false);
|
|
out.append(string);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Ensures all buffered data is written to the underlying {@link Writer}
|
|
* and flushes that writer.
|
|
*/
|
|
public void flush() throws IOException {
|
|
out.flush();
|
|
}
|
|
|
|
/**
|
|
* Flushes and closes this writer and the underlying {@link Writer}.
|
|
*
|
|
* @throws IOException if the JSON document is incomplete.
|
|
*/
|
|
public void close() throws IOException {
|
|
out.close();
|
|
|
|
if (peek() != JsonScope.NONEMPTY_DOCUMENT) {
|
|
throw new IOException("Incomplete document");
|
|
}
|
|
}
|
|
|
|
private void string(String value) throws IOException {
|
|
out.write("\"");
|
|
for (int i = 0, length = value.length(); i < length; i++) {
|
|
char c = value.charAt(i);
|
|
|
|
/*
|
|
* From RFC 4627, "All Unicode characters may be placed within the
|
|
* quotation marks except for the characters that must be escaped:
|
|
* quotation mark, reverse solidus, and the control characters
|
|
* (U+0000 through U+001F)."
|
|
*
|
|
* We also escape '\u2028' and '\u2029', which JavaScript interprets
|
|
* as newline characters. This prevents eval() from failing with a
|
|
* syntax error.
|
|
* http://code.google.com/p/google-gson/issues/detail?id=341
|
|
*/
|
|
switch (c) {
|
|
case '"':
|
|
case '\\':
|
|
out.write('\\');
|
|
out.write(c);
|
|
break;
|
|
|
|
case '\t':
|
|
out.write("\\t");
|
|
break;
|
|
|
|
case '\b':
|
|
out.write("\\b");
|
|
break;
|
|
|
|
case '\n':
|
|
out.write("\\n");
|
|
break;
|
|
|
|
case '\r':
|
|
out.write("\\r");
|
|
break;
|
|
|
|
case '\f':
|
|
out.write("\\f");
|
|
break;
|
|
|
|
case '\u2028':
|
|
case '\u2029':
|
|
out.write(String.format("\\u%04x", (int) c));
|
|
break;
|
|
|
|
default:
|
|
if (c <= 0x1F) {
|
|
out.write(String.format("\\u%04x", (int) c));
|
|
} else {
|
|
out.write(c);
|
|
}
|
|
break;
|
|
}
|
|
|
|
}
|
|
out.write("\"");
|
|
}
|
|
|
|
private void newline() throws IOException {
|
|
if (indent == null) {
|
|
return;
|
|
}
|
|
|
|
out.write("\n");
|
|
for (int i = 1; i < stack.size(); i++) {
|
|
out.write(indent);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Inserts any necessary separators and whitespace before a name. Also
|
|
* adjusts the stack to expect the name's value.
|
|
*/
|
|
private void beforeName() throws IOException {
|
|
JsonScope context = peek();
|
|
if (context == JsonScope.NONEMPTY_OBJECT) { // first in object
|
|
out.write(',');
|
|
} else if (context != JsonScope.EMPTY_OBJECT) { // not in an object!
|
|
throw new IllegalStateException("Nesting problem: " + stack);
|
|
}
|
|
newline();
|
|
replaceTop(JsonScope.DANGLING_NAME);
|
|
}
|
|
|
|
/**
|
|
* Inserts any necessary separators and whitespace before a literal value,
|
|
* inline array, or inline object. Also adjusts the stack to expect either a
|
|
* closing bracket or another element.
|
|
*
|
|
* @param root true if the value is a new array or object, the two values
|
|
* permitted as top-level elements.
|
|
*/
|
|
private void beforeValue(boolean root) throws IOException {
|
|
switch (peek()) {
|
|
case EMPTY_DOCUMENT: // first in document
|
|
if (!lenient && !root) {
|
|
throw new IllegalStateException(
|
|
"JSON must start with an array or an object.");
|
|
}
|
|
replaceTop(JsonScope.NONEMPTY_DOCUMENT);
|
|
break;
|
|
|
|
case EMPTY_ARRAY: // first in array
|
|
replaceTop(JsonScope.NONEMPTY_ARRAY);
|
|
newline();
|
|
break;
|
|
|
|
case NONEMPTY_ARRAY: // another in array
|
|
out.append(',');
|
|
newline();
|
|
break;
|
|
|
|
case DANGLING_NAME: // value for name
|
|
out.append(separator);
|
|
replaceTop(JsonScope.NONEMPTY_OBJECT);
|
|
break;
|
|
|
|
case NONEMPTY_DOCUMENT:
|
|
throw new IllegalStateException(
|
|
"JSON must have only one top-level value.");
|
|
|
|
default:
|
|
throw new IllegalStateException("Nesting problem: " + stack);
|
|
}
|
|
}
|
|
}
|