public interface JsonGenerator
extends java.io.Flushable, java.io.Closeable
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();
Other JSON values (that are not JSON objects or arrays) can be created
by calling the appropiate write
methods.
The following example shows how to generate a JSON string:
JsonGenerator generator = ...;
generator.write("message").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 7159.Json
,
JsonGeneratorFactory
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
PRETTY_PRINTING
Configuration property to generate JSON prettily.
|
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(java.math.BigDecimal value)
Writes the specified value as a JSON number value within
the current array, field or root context.
|
JsonGenerator |
write(java.math.BigInteger value)
Writes the specified value as a JSON number value within
the current array, field or root context.
|
JsonGenerator |
write(boolean value)
Writes a JSON true or false value within the current array, field or root context.
|
JsonGenerator |
write(double value)
Writes the specified value as a JSON number value within the current
array, field or root context.
|
JsonGenerator |
write(int value)
Writes the specified value as a JSON number value within
the current array, field or root context.
|
JsonGenerator |
write(JsonValue value)
Writes the specified value as a JSON value within
the current array, field or root context.
|
JsonGenerator |
write(long value)
Writes the specified value as a JSON number value within
the current array, field or root context.
|
JsonGenerator |
write(java.lang.String value)
Writes the specified value as a JSON string value within
the current array, field or root context.
|
JsonGenerator |
write(java.lang.String name,
java.math.BigDecimal value)
Writes a JSON name/number value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
java.math.BigInteger value)
Writes a JSON name/number value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
boolean value)
Writes a JSON name/boolean value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
double value)
Writes a JSON name/number value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
int value)
Writes a JSON name/number value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
JsonValue value)
Writes a JSON name/value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
long value)
Writes a JSON name/number value pair in the current object context.
|
JsonGenerator |
write(java.lang.String name,
java.lang.String value)
Writes a JSON name/string value pair in the current object context.
|
JsonGenerator |
writeEnd()
Writes the end of the current context.
|
JsonGenerator |
writeKey(java.lang.String name)
Writes the JSON name with a colon.
|
JsonGenerator |
writeNull()
Writes a JSON null value within the current array, field or root context.
|
JsonGenerator |
writeNull(java.lang.String name)
Writes a JSON name/null value pair in an current object context.
|
JsonGenerator |
writeStartArray()
Writes the JSON start array character.
|
JsonGenerator |
writeStartArray(java.lang.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(java.lang.String name)
Writes the JSON name/start object character pair in the current
object context.
|
static final java.lang.String PRETTY_PRINTING
JsonGenerator writeStartObject()
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.JsonGenerator writeStartObject(java.lang.String name)
name
- a name within the JSON name/object pair to be writtenJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object contextJsonGenerator writeKey(java.lang.String name)
name
- name of json fieldJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object contextJsonGenerator writeStartArray()
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 contextJsonGenerator writeStartArray(java.lang.String name)
name
- a name within the JSON name/array pair to be writtenJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within
an object contextJsonGenerator write(java.lang.String name, JsonValue value)
name
- a name in the JSON name/value pair to be written in
current JSON objectvalue
- a value in the JSON name/value pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object contextJsonGenerator write(java.lang.String name, java.lang.String value)
name
- a name in the JSON name/string pair to be written in
current JSON objectvalue
- a value in the JSON name/string pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object contextJsonGenerator write(java.lang.String name, java.math.BigInteger value)
new BigDecimal(value).toString()
is used as the text value for writing.name
- a name in the JSON name/number pair to be written in
current JSON objectvalue
- a value in the JSON name/number pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object context.JsonGenerator write(java.lang.String name, java.math.BigDecimal value)
toString()
is used as the text value for writing.name
- a name in the JSON name/number pair to be written in
current JSON objectvalue
- a value in the JSON name/number pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object context.JsonGenerator write(java.lang.String name, int value)
new BigDecimal(value).toString()
is used as the text value
for writing.name
- a name in the JSON name/number pair to be written in
current JSON objectvalue
- a value in the JSON name/number pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object context.JsonGenerator write(java.lang.String name, long value)
new BigDecimal(value).toString()
is used as the text
value for writing.name
- a name in the JSON name/number pair to be written in
current JSON objectvalue
- a value in the JSON name/number pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object context.JsonGenerator write(java.lang.String name, double value)
BigDecimal.valueOf(double).toString()
is used as the text value for writing.name
- a name in the JSON name/number pair to be written in
current JSON objectvalue
- a value in the JSON name/number pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)java.lang.NumberFormatException
- if the value is Not-a-Number (NaN) or infinity.JsonGenerationException
- if this method is not called within an
object contextJsonGenerator write(java.lang.String name, boolean value)
true
value, otherwise
it writes the JSON false
value.name
- a name in the JSON name/boolean pair to be written in
current JSON objectvalue
- a value in the JSON name/boolean pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object context.JsonGenerator writeNull(java.lang.String name)
name
- a name in the JSON name/null pair to be written in
current JSON objectJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
object contextJsonGenerator writeEnd()
JsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is called in no context.JsonGenerator write(JsonValue value)
value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonGenerator write(java.lang.String value)
value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonGenerator write(java.math.BigDecimal value)
toString()
is used as the the text value for writing.value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonNumber
JsonGenerator write(java.math.BigInteger value)
new BigDecimal(value).toString()
is used as the text value for writing.value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonNumber
JsonGenerator write(int value)
new BigDecimal(value).toString()
is used as the text value for writing.value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonGenerator write(long value)
new BigDecimal(value).toString()
is used as the text value for writing.value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonGenerator write(double value)
BigDecimal.valueOf(value).toString()
is used as the text value for writing.value
- a value to be written in current JSON arrayJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.java.lang.NumberFormatException
- if the value is Not-a-Number (NaN) or infinity.JsonGenerator write(boolean value)
true
value,
otherwise it writes the JSON false
value.value
- a boolean
valueJsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.JsonGenerator writeNull()
JsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if this method is not called within an
array, root or field context.void close()
close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
JsonException
- if an i/o error occurs (IOException
would be cause of JsonException)JsonGenerationException
- if an incomplete JSON is generatedvoid flush()
flush
in interface java.io.Flushable
JsonException
- if an i/o error occurs (IOException
would be cause of JsonException)