Java tutorial
/* * 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}. */ 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); } } }