JsonGenerator (JavaEE Full Profile API)

All Superinterfaces:: AutoCloseable, Closeable, Flushable

public interface JsonGenerator
extends Flushable, Closeable

A JSON generator that writes JSON in a streaming way. The generator can be created from many output sources like Writer and OutputStream.

For example, a generator can be created as follows:

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

A generator can also be created using JsonGeneratorFactory. If multiple generator instances are created, then creating them using a generator factory is preferred.

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

The generator is used to generate JSON object in a streaming way by calling its writeStartObject() method and writing name/value pairs.

For example 1:

Empty JSON object can be generated as follows:

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

The generator is used to generate JSON array in a streaming way by calling its writeStartArray() method and adding values.

For example 2:

Empty JSON array can be generated as follows:

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

The generator methods can be chained. Similarly, the following generator

 
 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();

would generate a JSON equivalent to the following:

 
 {
   "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 the RFC.

Author:: Jitendra Kotamraju
See Also:: Json, JsonGeneratorFactory

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this generator and frees any resources associated with the generator.
`void`	`flush()`
`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.The `BigDecimal.valueOf(value).toString()` is used as the text value for writing.
`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 with in the current object context.
`JsonGenerator`	`write(String name, BigInteger value)` Writes a JSON name/number value pair with in the current object context.
`JsonGenerator`	`write(String name, boolean value)` Writes a JSON name/boolean value pair with in the current object context.
`JsonGenerator`	`write(String name, double value)` Writes a JSON name/number value pair with in the current object context.
`JsonGenerator`	`write(String name, int value)` Writes a JSON name/number value pair with in the current object context.
`JsonGenerator`	`write(String name, JsonValue value)` Writes a JSON name/value pair with in the current object context.
`JsonGenerator`	`write(String name, long value)` Writes a JSON name/number value pair with in the current object context.
`JsonGenerator`	`write(String name, String value)` Writes a JSON name/string value pair with in the current object context.
`JsonGenerator`	`writeEnd()` Indicates the writeEnd 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 with 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 with in the current object context.

- 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 called within object context or if called more than once in no context
  - writeStartObject
```
JsonGenerator writeStartObject(String name)
```
    Writes the JSON name/start object character pair with 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 not called within 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 called within 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 not called within object context
  - write
```
JsonGenerator write(String name,
                  JsonValue value)
```
    Writes a JSON name/value pair with in the current object context.
    
    Parameters:
    name - a name in the JSON name/value pair to be written within current JSON object
    value - a value in the JSON name/value pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  String value)
```
    Writes a JSON name/string value pair with 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 within current JSON object
    value - a value in the JSON name/string pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  BigInteger value)
```
    Writes a JSON name/number value pair with in the current object context. The specified value is written as a JSON number value. The 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 within current JSON object
    value - a value in the JSON name/number pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  BigDecimal value)
```
    Writes a JSON name/number value pair with 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 within current JSON object
    value - a value in the JSON name/number pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  int value)
```
    Writes a JSON name/number value pair with in the current object context. The specified value is written as a JSON number value. The 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 within current JSON object
    value - a value in the JSON name/number pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  long value)
```
    Writes a JSON name/number value pair with in the current object context. The specified value is written as a JSON number value. The 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 within current JSON object
    value - a value in the JSON name/number pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  double value)
```
    Writes a JSON name/number value pair with in the current object context. The specified value is written as a JSON number value. The 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 within current JSON object
    value - a value in the JSON name/number pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    NumberFormatException - if value is Not-a-Number(NaN) or infinity
    
    JsonGenerationException - if not called within object context
  - write
```
JsonGenerator write(String name,
                  boolean value)
```
    Writes a JSON name/boolean value pair with in the current object context. If value is true, it writes JSON true value, otherwise JSON false value.
    
    Parameters:
    name - a name in the JSON name/boolean pair to be written within current JSON object
    value - a value in the JSON name/boolean pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - writeNull
```
JsonGenerator writeNull(String name)
```
    Writes a JSON name/null value pair with in an current object context.
    
    Parameters:
    name - a name in the JSON name/null pair to be written within current JSON object
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within object context
  - writeEnd
```
JsonGenerator writeEnd()
```
    Indicates the writeEnd of the current context. If the current context is array context, the writeEnd of array char ']' is written. If the current context is object context, writeEnd of object char '}' is written. After writing, parent context would become the current context.
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if 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 within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within 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 within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within 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 within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within 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 new BigDecimal(value).toString() is used as the text value for writing.
    
    Parameters:
    value - a value to be written within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within 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 new BigDecimal(value).toString() is used as the text value for writing.
    
    Parameters:
    value - a value to be written within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within array context
  - write
```
JsonGenerator write(long value)
```
    Writes the specified value as a JSON number value within the current array context. The new BigDecimal(value).toString() is used as the text value for writing.
    
    Parameters:
    value - a value to be written within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within array context
  - write
```
JsonGenerator write(double value)
```
    Writes the specified value as a JSON number value within the current array context.The BigDecimal.valueOf(value).toString() is used as the text value for writing.
    
    Parameters:
    value - a value to be written within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within array context
    
    NumberFormatException - if 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, it writes JSON true value, otherwise JSON false value.
    
    Parameters:
    value - a value to be written within current JSON array
    
    Returns:
    this generator
    
    Throws:
    
    JsonException - if an i/o error occurs (IOException would be cause of JsonException)
    
    JsonGenerationException - if not called within 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 not called within array context
  - close
```
void close()
```
    Closes this generator and frees any resources associated with the generator. This 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()
```
    Specified by:
    
    flush in interface Flushable

Interface JsonGenerator

Method Summary

Method Detail

writeStartObject

writeStartObject

writeStartArray

writeStartArray

write

write

write

write

write

write

write

write

writeNull

writeEnd

write

write

write

write

write

write

write

write

writeNull

close

flush