Class JsonWriter

java.lang.Object
com.carrotsearch.ant.tasks.junit4.gson.stream.IOContext
com.carrotsearch.ant.tasks.junit4.gson.stream.JsonWriter
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable
public class JsonWriter extends IOContext implements Closeable, Flushable
Writes a JSON (RFC 4627) 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.

Encoding JSON

To encode your data as JSON, create a new 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:
  • To write arrays, first call beginArray(). Write each of the array's elements with the appropriate value(String) methods or by nesting other arrays and objects. Finally close the array using endArray().
  • To write objects, first call beginObject(). Write each of the object's properties by alternating calls to name(String) with the property's value. Write property values with the appropriate value(String) method or by nesting other objects or arrays. Finally close the object using endObject().

Example

Suppose we'd like to encode a stream of messages such as the following: 
[
  {
    "id": 912345678901,
    "text": "How do I stream JSON in Java?",
    "geo": null,
    "user": {
      "name": "json_newb",
      "followers_count": 41
     }
  },
  {
    "id": 912345678902,
    "text": "@json_newb just use JsonWriter!",
    "geo": [50.454722, -104.606667],
    "user": {
      "name": "jesse",
      "followers_count": 2
    }
  }
]
This code encodes the above structure: 
  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();
  }

Each 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 IllegalStateException.

Since:
1.6

  • Field Details

    • REPLACEMENT_CHARS

      private static final String[] REPLACEMENT_CHARS

    • HTML_SAFE_REPLACEMENT_CHARS

      private static final String[] HTML_SAFE_REPLACEMENT_CHARS

    • out

      private final Writer out
      The output data, containing at most one top-level array or object.

    • stack

      private int[] stack

    • stackSize

      private int stackSize

    • indent

      private String indent
      A string containing a full set of spaces for a single level of indentation, or null for no pretty printing.

    • separator

      private String separator
      The name/value separator; either ":" or ": ".

    • lenient

      private boolean lenient

    • htmlSafe

      private boolean htmlSafe

    • deferredName

      private String deferredName

    • serializeNulls

      private boolean serializeNulls

  • Constructor Details

    • JsonWriter

      public JsonWriter(Writer out)
      Creates a new instance that writes a JSON-encoded stream to out. For best performance, ensure Writer is buffered; wrapping in BufferedWriter if necessary.

  • Method Details

    • setIndent

      public final void setIndent(String indent)
      Sets the indentation string to be repeated for each level of indentation in the encoded document. If indent.isEmpty() the encoded document will be compact. Otherwise the encoded document will be more human-readable.
      Parameters:
      indent - a string containing only whitespace.

    • setLenient

      public final void setLenient(boolean lenient)
      Configure this writer to relax its syntax rules. By default, this writer only emits well-formed JSON as specified by RFC 4627. Setting the writer to lenient permits the following:
      • Top-level values of any type. With strict writing, the top-level value must be an object or an array.
      • Numbers may be NaNs or infinities.

    • isLenient

      public boolean isLenient()
      Returns true if this writer has relaxed syntax rules.

    • setHtmlSafe

      public final void setHtmlSafe(boolean htmlSafe)
      Configure this writer to emit JSON that's safe for direct inclusion in HTML and XML documents. This escapes the HTML characters <, >, & and = before writing them to the stream. Without this setting, your XML/HTML encoder should replace these characters with the corresponding escape sequences.

    • isHtmlSafe

      public final boolean isHtmlSafe()
      Returns true if this writer writes JSON that's safe for inclusion in HTML and XML documents.

    • setSerializeNulls

      public final void setSerializeNulls(boolean serializeNulls)
      Sets whether object members are serialized when their value is null. This has no impact on array elements. The default is true.

    • getSerializeNulls

      public final boolean getSerializeNulls()
      Returns true if object members are serialized when their value is null. This has no impact on array elements. The default is true.

    • beginArray

      public JsonWriter beginArray() throws IOException
      Begins encoding a new array. Each call to this method must be paired with a call to endArray().
      Returns:
      this writer.
      Throws:
      IOException

    • endArray

      public JsonWriter endArray() throws IOException
      Ends encoding the current array.
      Returns:
      this writer.
      Throws:
      IOException

    • beginObject

      public JsonWriter beginObject() throws IOException
      Begins encoding a new object. Each call to this method must be paired with a call to endObject().
      Returns:
      this writer.
      Throws:
      IOException

    • endObject

      public JsonWriter endObject() throws IOException
      Ends encoding the current object.
      Returns:
      this writer.
      Throws:
      IOException

    • open

      private JsonWriter open(int empty, String openBracket) throws IOException
      Enters a new scope by appending any necessary whitespace and the given bracket.
      Throws:
      IOException

    • close

      private JsonWriter close(int empty, int nonempty, String closeBracket) throws IOException
      Closes the current scope by appending any necessary whitespace and the given bracket.
      Throws:
      IOException

    • push

      private void push(int newTop)

    • peek

      private int peek()
      Returns the value on the top of the stack.

    • replaceTop

      private void replaceTop(int topOfStack)
      Replace the value on the top of the stack with the given value.

    • name

      public JsonWriter name(String name) throws IOException
      Encodes the property name.
      Parameters:
      name - the name of the forthcoming value. May not be null.
      Returns:
      this writer.
      Throws:
      IOException

    • writeDeferredName

      private void writeDeferredName() throws IOException
      Throws:
      IOException

    • value

      public JsonWriter value(String value) throws IOException
      Encodes value.
      Parameters:
      value - the literal string value, or null to encode a null literal.
      Returns:
      this writer.
      Throws:
      IOException

    • jsonValue

      public JsonWriter jsonValue(String value) throws IOException
      Writes value directly to the writer without quoting or escaping.
      Parameters:
      value - the literal string value, or null to encode a null literal.
      Returns:
      this writer.
      Throws:
      IOException

    • nullValue

      public JsonWriter nullValue() throws IOException
      Encodes null.
      Returns:
      this writer.
      Throws:
      IOException

    • value

      public JsonWriter value(boolean value) throws IOException
      Encodes value.
      Returns:
      this writer.
      Throws:
      IOException

    • value

      public JsonWriter value(double value) throws IOException
      Encodes value.
      Parameters:
      value - a finite value. May not be NaNs or infinities.
      Returns:
      this writer.
      Throws:
      IOException

    • value

      public JsonWriter value(long value) throws IOException
      Encodes value.
      Returns:
      this writer.
      Throws:
      IOException

    • value

      public JsonWriter value(Number value) throws IOException
      Encodes value.
      Parameters:
      value - a finite value. May not be NaNs or infinities.
      Returns:
      this writer.
      Throws:
      IOException

    • flush

      public void flush() throws IOException
      Ensures all buffered data is written to the underlying Writer and flushes that writer.
      Specified by:
      flush in interface Flushable
      Throws:
      IOException

    • close

      public void close() throws IOException
      Flushes and closes this writer and the underlying Writer.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if the JSON document is incomplete.

    • string

      private void string(String value) throws IOException
      Throws:
      IOException

    • newline

      private void newline() throws IOException
      Throws:
      IOException

    • beforeName

      private void beforeName() throws IOException
      Inserts any necessary separators and whitespace before a name. Also adjusts the stack to expect the name's value.
      Throws:
      IOException

    • beforeValue

      private void beforeValue(boolean root) throws IOException
      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.
      Parameters:
      root - true if the value is a new array or object, the two values permitted as top-level elements.
      Throws:
      IOException