javax.json.stream

## Interface JsonGenerator

- All Superinterfaces:
    AutoCloseable, Closeable, Flushable

      public interface JsonGenerator
      extends Flushable, Closeable

  Writes JSON data to an output source in a streaming way. The class `Json` contains methods to create generators for character or output streams (`Writer` and `OutputStream`).

  The following example shows how to create a JSON generator:

       JsonGenerator generator = Json.createGenerator(...);

  The class `JsonGeneratorFactory` also contains methods to create `JsonGenerator` instances. `JsonGeneratorFactory` should be used when creating multiple generator instances, as in the following example:

       JsonGeneratorFactory factory = Json.createGeneratorFactory();
       JsonGenerator generator1 = factory.createGenerator(...);
       JsonGenerator generator2 = factory.createGenerator(...);

  JSON objects can be created using `JsonGenerator` by calling the `writeStartObject()` method and then adding name/value pairs with the `write` method.

  The following example shows how to generate an empty JSON object:

       JsonGenerator generator = ...;
       generator.writeStartObject().writeEnd().close();

  JSON arrays can be created using `JsonGenerator` by calling the `writeStartArray()` method and then adding values with the `write` method.

  The following example shows how to generate an empty JSON array:

       JsonGenerator generator = ...;
       generator.writeStartArray().writeEnd().close();

  `JsonGenerator` methods can be chained as in the following example:

       generator
           .writeStartObject()
               .write("firstName", "John")
               .write("lastName", "Smith")
               .write("age", 25)
               .writeStartObject("address")
                   .write("streetAddress", "21 2nd Street")
                   .write("city", "New York")
                   .write("state", "NY")
                   .write("postalCode", "10021")
               .writeEnd()
               .writeStartArray("phoneNumber")
                   .writeStartObject()
                       .write("type", "home")
                       .write("number", "212 555-1234")
                   .writeEnd()
                   .writeStartObject()
                       .write("type", "fax")
                       .write("number", "646 555-4567")
                   .writeEnd()
               .writeEnd()
           .writeEnd();
       generator.close();

  The example code above generates the following JSON (or equivalent):

       {
         "firstName": "John", "lastName": "Smith", "age": 25,
         "address" : {
             "streetAddress": "21 2nd Street",
             "city": "New York",
             "state": "NY",
             "postalCode": "10021"
         },
         "phoneNumber": [
             {"type": "home", "number": "212 555-1234"},
             {"type": "fax", "number": "646 555-4567"}
          ]
       }

  The generated JSON text must strictly conform to the grammar defined in RFC 4627.
  Author:
    Jitendra Kotamraju
  See Also:
    `Json`, `JsonGeneratorFactory`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `PRETTY_PRINTING` Configuration property to generate JSON prettily.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this generator and frees any resources associated with it.
    `void` | `flush()` Flushes the underlying output source.
    `JsonGenerator` | `write(BigDecimal value)` Writes the specified value as a JSON number value within the current array context.
    `JsonGenerator` | `write(BigInteger value)` Writes the specified value as a JSON number value within the current array context.
    `JsonGenerator` | `write(boolean value)` Writes a JSON true or false value within the current array context.
    `JsonGenerator` | `write(double value)` Writes the specified value as a JSON number value within the current array context.
    `JsonGenerator` | `write(int value)` Writes the specified value as a JSON number value within the current array context.
    `JsonGenerator` | `write(JsonValue value)` Writes the specified value as a JSON value within the current array context.
    `JsonGenerator` | `write(long value)` Writes the specified value as a JSON number value within the current array context.
    `JsonGenerator` | `write(String value)` Writes the specified value as a JSON string value within the current array context.
    `JsonGenerator` | `write(String name, BigDecimal value)` Writes a JSON name/number value pair in the current object context.
    `JsonGenerator` | `write(String name, BigInteger value)` Writes a JSON name/number value pair in the current object context.
    `JsonGenerator` | `write(String name, boolean value)` Writes a JSON name/boolean value pair in the current object context.
    `JsonGenerator` | `write(String name, double value)` Writes a JSON name/number value pair in the current object context.
    `JsonGenerator` | `write(String name, int value)` Writes a JSON name/number value pair in the current object context.
    `JsonGenerator` | `write(String name, JsonValue value)` Writes a JSON name/value pair in the current object context.
    `JsonGenerator` | `write(String name, long value)` Writes a JSON name/number value pair in the current object context.
    `JsonGenerator` | `write(String name, String value)` Writes a JSON name/string value pair in the current object context.
    `JsonGenerator` | `writeEnd()` Writes the end of the current context.
    `JsonGenerator` | `writeNull()` Writes a JSON null value within the current array context.
    `JsonGenerator` | `writeNull(String name)` Writes a JSON name/null value pair in an current object context.
    `JsonGenerator` | `writeStartArray()` Writes the JSON start array character.
    `JsonGenerator` | `writeStartArray(String name)` Writes the JSON name/start array character pair with in the current object context.
    `JsonGenerator` | `writeStartObject()` Writes the JSON start object character.
    `JsonGenerator` | `writeStartObject(String name)` Writes the JSON name/start object character pair in the current object context.

- - ### Field Detail

    - #### PRETTY_PRINTING

          static final String PRETTY_PRINTING

      Configuration property to generate JSON prettily. All providers must support this property. The value of the property could be be anything.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### writeStartObject

          JsonGenerator writeStartObject()

      Writes the JSON start object character. It starts a new child object context within which JSON name/value pairs can be written to the object. This method is valid only in an array context or in no context (when a context is not yet started). This method can only be called once in no context.
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is called within an object context or if it is called more than once in no context.

    - #### writeStartObject

          JsonGenerator writeStartObject(String name)

      Writes the JSON name/start object character pair in the current object context. It starts a new child object context within which JSON name/value pairs can be written to the object.
      Parameters:
        `name` - a name within the JSON name/object pair to be written
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context

    - #### writeStartArray

          JsonGenerator writeStartArray()

      Writes the JSON start array character. It starts a new child array context within which JSON values can be written to the array. This method is valid only in an array context or in no context (when a context is not yet started). This method can only be called once in no context.
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is called within an object context or if called more than once in no context

    - #### writeStartArray

          JsonGenerator writeStartArray(String name)

      Writes the JSON name/start array character pair with in the current object context. It starts a new child array context within which JSON values can be written to the array.
      Parameters:
        `name` - a name within the JSON name/array pair to be written
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context

    - #### write

          JsonGenerator write(String name,
                            JsonValue value)

      Writes a JSON name/value pair in the current object context.
      Parameters:
        `name` - a name in the JSON name/value pair to be written in current JSON object
        `value` - a value in the JSON name/value pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context

    - #### write

          JsonGenerator write(String name,
                            String value)

      Writes a JSON name/string value pair in the current object context. The specified value is written as JSON string value.
      Parameters:
        `name` - a name in the JSON name/string pair to be written in current JSON object
        `value` - a value in the JSON name/string pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context

    - #### write

          JsonGenerator write(String name,
                            BigInteger value)

      Writes a JSON name/number value pair in the current object context. The specified value is written as a JSON number value. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `name` - a name in the JSON name/number pair to be written in current JSON object
        `value` - a value in the JSON name/number pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context.

    - #### write

          JsonGenerator write(String name,
                            BigDecimal value)

      Writes a JSON name/number value pair in the current object context. The specified value is written as a JSON number value. The specified value's `toString()` is used as the text value for writing.
      Parameters:
        `name` - a name in the JSON name/number pair to be written in current JSON object
        `value` - a value in the JSON name/number pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context.

    - #### write

          JsonGenerator write(String name,
                            int value)

      Writes a JSON name/number value pair in the current object context. The specified value is written as a JSON number value. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `name` - a name in the JSON name/number pair to be written in current JSON object
        `value` - a value in the JSON name/number pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context.

    - #### write

          JsonGenerator write(String name,
                            long value)

      Writes a JSON name/number value pair in the current object context. The specified value is written as a JSON number value. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `name` - a name in the JSON name/number pair to be written in current JSON object
        `value` - a value in the JSON name/number pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context.

    - #### write

          JsonGenerator write(String name,
                            double value)

      Writes a JSON name/number value pair in the current object context. The specified value is written as a JSON number value. The string `BigDecimal.valueOf(double).toString()` is used as the text value for writing.
      Parameters:
        `name` - a name in the JSON name/number pair to be written in current JSON object
        `value` - a value in the JSON name/number pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `NumberFormatException` - if the value is Not-a-Number(NaN) or infinity.
        `JsonGenerationException` - if this method is not called within an object context

    - #### write

          JsonGenerator write(String name,
                            boolean value)

      Writes a JSON name/boolean value pair in the current object context. If value is true, it writes the JSON `true` value, otherwise it writes the JSON `false` value.
      Parameters:
        `name` - a name in the JSON name/boolean pair to be written in current JSON object
        `value` - a value in the JSON name/boolean pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context.

    - #### writeNull

          JsonGenerator writeNull(String name)

      Writes a JSON name/null value pair in an current object context.
      Parameters:
        `name` - a name in the JSON name/null pair to be written in current JSON object
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an object context

    - #### writeEnd

          JsonGenerator writeEnd()

      Writes the end of the current context. If the current context is an array context, this method writes the end-of-array character (']'). If the current context is an object context, this method writes the end-of-object character ('}'). After writing the end of the current context, the parent context becomes the new current context.
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is called in no context.

    - #### write

          JsonGenerator write(JsonValue value)

      Writes the specified value as a JSON value within the current array context.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context.

    - #### write

          JsonGenerator write(String value)

      Writes the specified value as a JSON string value within the current array context.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context

    - #### write

          JsonGenerator write(BigDecimal value)

      Writes the specified value as a JSON number value within the current array context. The specified value's `toString()` is used as the the text value for writing.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context
      See Also:
        `JsonNumber`

    - #### write

          JsonGenerator write(BigInteger value)

      Writes the specified value as a JSON number value within the current array context. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator.
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context
      See Also:
        `JsonNumber`

    - #### write

          JsonGenerator write(int value)

      Writes the specified value as a JSON number value within the current array context. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context

    - #### write

          JsonGenerator write(long value)

      Writes the specified value as a JSON number value within the current array context. The string `new BigDecimal(value).toString()` is used as the text value for writing.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context

    - #### write

          JsonGenerator write(double value)

      Writes the specified value as a JSON number value within the current array context. The string `BigDecimal.valueOf(value).toString()` is used as the text value for writing.
      Parameters:
        `value` - a value to be written in current JSON array
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context
        `NumberFormatException` - if the value is Not-a-Number(NaN) or infinity.

    - #### write

          JsonGenerator write(boolean value)

      Writes a JSON true or false value within the current array context. If value is true, this method writes the JSON `true` value, otherwise it writes the JSON `false` value.
      Parameters:
        `value` - a `boolean` value
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context.

    - #### writeNull

          JsonGenerator writeNull()

      Writes a JSON null value within the current array context.
      Returns:
        this generator
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if this method is not called within an array context

    - #### close

          void close()

      Closes this generator and frees any resources associated with it. This method closes the underlying output source.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)
        `JsonGenerationException` - if an incomplete JSON is generated

    - #### flush

          void flush()

      Flushes the underlying output source. If the generator has saved any characters in a buffer, writes them immediately to the underlying output source before flushing it.
      Specified by:
        `flush` in interface `Flushable`
      Throws:
        `JsonException` - if an i/o error occurs (IOException would be cause of JsonException)

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.