Package javax.json.stream
Interface JsonGenerator
-
- All Superinterfaces:
java.lang.AutoCloseable
,java.io.Closeable
,java.io.Flushable
public interface JsonGenerator extends java.io.Flushable, java.io.Closeable
Writes JSON data to an output source in a streaming way. The classJson
contains methods to create generators for character or output streams (Writer
andOutputStream
).
This is a near-exact copy of the same-titled Java EE 8 Class:javax.json.stream.JsonGenerator
Commenting has been slightly modified to accompany HiLited Code Examples.
Java Source Code remains identical to the Sun-Oracle & 'GlassFish' Released Distributions.
Read included License:HERE
, and theCDDL+GPL-1.1
Alljavax.json.stream.*
Code Obtained From:GitHub JavaEE jsonp
Public Archive.
The following example shows how to create a JSON generator:
JsonGenerator generator = Json.createGenerator(...);
The classJsonGeneratorFactory
also contains methods to createJsonGenerator
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 usingJsonGenerator
by calling thewriteStartObject()
method and then adding name/value pairs with thewrite
method.
The following example shows how to generate an empty JSON object:
JsonGenerator generator = ...; generator.writeStartObject().writeEnd().close();
JSON arrays can be created usingJsonGenerator
by calling thewriteStartArray()
method and then adding values with thewrite
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 appropiatewrite
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:
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):
Java Script Object Notation (JSON):
{ "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.- See Also:
Json
,JsonGeneratorFactory
Hi-Lited Source-Code:This File's Source Code:
- View Here: javax/json/stream/JsonGenerator.java
- Open New Browser-Tab: javax/json/stream/JsonGenerator.java
File Size: 22,708 Bytes Line Count: 561 '\n' Characters Found
Glass Fish Implementation Class:
- View Here: org/glassfish/json/JsonGeneratorImpl.java
- Open New Browser-Tab: org/glassfish/json/JsonGeneratorImpl.java
File Size: 23,922 Bytes Line Count: 735 '\n' Characters Found
Extra Glass Fish Implementation Class:
- View Here: org/glassfish/json/JsonPrettyGeneratorImpl.java
- Open New Browser-Tab: org/glassfish/json/JsonPrettyGeneratorImpl.java
File Size: 3,969 Bytes Line Count: 130 '\n' Characters Found
-
-
Field Summary
Fields Modifier and Type Field Description static String
PRETTY_PRINTING
Configuration property to generate JSON prettily.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Closes this generator and frees any resources associated with it.void
flush()
Flushes the underlying output source.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(long value)
Writes the specified value as a JSON number value within the current array, field or root context.JsonGenerator
write(String value)
Writes the specified value as a JSON string value within the current array, field or root 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, 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
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, JsonValue value)
Writes a JSON name/value pair in the current object context.JsonGenerator
write(BigDecimal value)
Writes the specified value as a JSON number value within the current array, field or root context.JsonGenerator
write(BigInteger 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
writeEnd()
Writes the end of the current context.JsonGenerator
writeKey(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(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 java.lang.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
- Code:
- Exact Field Declaration Expression:
String PRETTY_PRINTING = "javax.json.stream.JsonGenerator.prettyPrinting"
-
-
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, field 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(java.lang.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
-
writeKey
JsonGenerator writeKey(java.lang.String name)
Writes the JSON name with a colon. It starts a field context, in which valid options are writing a value, starting an object or an array. Writing value closes field context, if object or array is started after field name, field context will be closed after object/array close.- Parameters:
name
- name of json field- 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- Since:
- 1.1
-
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, field 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(java.lang.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(java.lang.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 objectvalue
- 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(java.lang.String name, java.lang.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 objectvalue
- 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(java.lang.String name, java.math.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 stringnew 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 objectvalue
- 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(java.lang.String name, java.math.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'stoString()
is used as the text value for writing.- Parameters:
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 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(java.lang.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 stringnew 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 objectvalue
- 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(java.lang.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 stringnew 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 objectvalue
- 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(java.lang.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 stringBigDecimal.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 objectvalue
- 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)java.lang.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(java.lang.String name, boolean value)
Writes a JSON name/boolean value pair in the current object context. If value is true, it writes the JSONtrue
value, otherwise it writes the JSONfalse
value.- Parameters:
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 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(java.lang.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. If parent context is field context, it is closed.- 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, field or root 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 or root context.
-
write
JsonGenerator write(java.lang.String value)
Writes the specified value as a JSON string value within the current array, field or root 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 or root context.
-
write
JsonGenerator write(java.math.BigDecimal value)
Writes the specified value as a JSON number value within the current array, field or root context. The specified value'stoString()
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 or root context.- See Also:
JsonNumber
-
write
JsonGenerator write(java.math.BigInteger value)
Writes the specified value as a JSON number value within the current array, field or root context. The stringnew 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 or root context.- See Also:
JsonNumber
-
write
JsonGenerator write(int value)
Writes the specified value as a JSON number value within the current array, field or root context. The stringnew 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 or root context.
-
write
JsonGenerator write(long value)
Writes the specified value as a JSON number value within the current array, field or root context. The stringnew 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 or root context.
-
write
JsonGenerator write(double value)
Writes the specified value as a JSON number value within the current array, field or root context. The stringBigDecimal.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 or root context.java.lang.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, field or root context. If value is true, this method writes the JSONtrue
value, otherwise it writes the JSONfalse
value.- Parameters:
value
- aboolean
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 or root context.
-
writeNull
JsonGenerator writeNull()
Writes a JSON null value within the current array, field or root 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 or root 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.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 interfacejava.io.Flushable
- Throws:
JsonException
- if an i/o error occurs (IOException would be cause of JsonException)
-
-