Package com.google.gson.stream
Class JsonWriter
java.lang.Object
com.google.gson.stream.JsonWriter
- All Implemented Interfaces:
Closeable
,Flushable
,AutoCloseable
- Direct Known Subclasses:
JsonTreeWriter
Writes a JSON (RFC 8259) 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 newJsonWriter
. 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 appropriatevalue(java.lang.String)
methods or by nesting other arrays and objects. Finally close the array usingendArray()
. - To write objects, first call
beginObject()
. Write each of the object's properties by alternating calls toname(java.lang.String)
with the property's value. Write property values with the appropriatevalue(java.lang.String)
method or by nesting other objects or arrays. Finally close the object usingendObject()
.
Configuration
The behavior of this writer can be customized with the following methods:setFormattingStyle(FormattingStyle)
, the default isFormattingStyle.COMPACT
setHtmlSafe(boolean)
, by default HTML characters are not escaped in the JSON outputsetStrictness(Strictness)
, the default isStrictness.LEGACY_STRICT
setSerializeNulls(boolean)
, by defaultnull
is serialized
JsonWriter
instances used internally by the Gson
class differs, and can be adjusted with the various GsonBuilder
methods.
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 Summary
FieldsModifier and TypeFieldDescriptionprivate String
private String
private String
private FormattingStyle
private static final String[]
private boolean
private final Writer
The JSON output destinationprivate static final String[]
private boolean
private int[]
private int
private Strictness
private boolean
private static final Pattern
-
Constructor Summary
ConstructorsConstructorDescriptionJsonWriter
(Writer out) Creates a new instance that writes a JSON-encoded stream toout
. -
Method Summary
Modifier and TypeMethodDescriptionprivate static boolean
alwaysCreatesValidJsonNumber
(Class<? extends Number> c) Returns whether thetoString()
ofc
will always return a valid JSON number.private void
Inserts any necessary separators and whitespace before a name.private void
Inserts any necessary separators and whitespace before a literal value, inline array, or inline object.Begins encoding a new array.Begins encoding a new object.void
close()
Flushes and closes this writer and the underlyingWriter
.private JsonWriter
closeScope
(int empty, int nonempty, char closeBracket) Closes the current scope by appending any necessary whitespace and the given bracket.endArray()
Ends encoding the current array.Ends encoding the current object.void
flush()
Ensures all buffered data is written to the underlyingWriter
and flushes that writer.final FormattingStyle
Returns the pretty printing style used by this writer.final boolean
Returns true if object members are serialized when their value is null.final Strictness
Returns the strictness of this writer.final boolean
Returns true if this writer writes JSON that's safe for inclusion in HTML and XML documents.boolean
Returns true if theStrictness
of this writer is equal toStrictness.LENIENT
.Writesvalue
directly to the writer without quoting or escaping.Encodes the property name.private void
newline()
Encodesnull
.private JsonWriter
openScope
(int empty, char openBracket) Enters a new scope by appending any necessary whitespace and the given bracket.private int
peek()
Returns the value on the top of the stack.private void
push
(int newTop) private void
replaceTop
(int topOfStack) Replace the value on the top of the stack with the given value.final void
setFormattingStyle
(FormattingStyle formattingStyle) Sets the formatting style to be used in the encoded document.final void
setHtmlSafe
(boolean htmlSafe) Configures this writer to emit JSON that's safe for direct inclusion in HTML and XML documents.final void
Sets the indentation string to be repeated for each level of indentation in the encoded document.final void
setLenient
(boolean lenient) Deprecated.final void
setSerializeNulls
(boolean serializeNulls) Sets whether object members are serialized when their value is null.final void
setStrictness
(Strictness strictness) Configures how strict this writer is with regard to the syntax rules specified in RFC 8259.private void
value
(boolean value) Encodesvalue
.value
(double value) Encodesvalue
.value
(float value) Encodesvalue
.value
(long value) Encodesvalue
.Encodesvalue
.Encodesvalue
.Encodesvalue
.private void
-
Field Details
-
VALID_JSON_NUMBER_PATTERN
-
REPLACEMENT_CHARS
-
HTML_SAFE_REPLACEMENT_CHARS
-
out
The JSON output destination -
stack
private int[] stack -
stackSize
private int stackSize -
formattingStyle
-
formattedColon
-
formattedComma
-
usesEmptyNewlineAndIndent
private boolean usesEmptyNewlineAndIndent -
strictness
-
htmlSafe
private boolean htmlSafe -
deferredName
-
serializeNulls
private boolean serializeNulls
-
-
Constructor Details
-
JsonWriter
Creates a new instance that writes a JSON-encoded stream toout
. For best performance, ensureWriter
is buffered; wrapping inBufferedWriter
if necessary.
-
-
Method Details
-
setIndent
Sets the indentation string to be repeated for each level of indentation in the encoded document. Ifindent.isEmpty()
the encoded document will be compact. Otherwise the encoded document will be more human-readable.This is a convenience method which overwrites any previously set formatting style with either
FormattingStyle.COMPACT
if the given indent string is empty, orFormattingStyle.PRETTY
with the given indent if not empty.- Parameters:
indent
- a string containing only whitespace.
-
setFormattingStyle
Sets the formatting style to be used in the encoded document.The formatting style specifies for example the indentation string to be repeated for each level of indentation, or the newline style, to accommodate various OS styles.
- Parameters:
formattingStyle
- the formatting style to use, must not benull
.- Since:
- 2.11.0
- See Also:
-
getFormattingStyle
Returns the pretty printing style used by this writer.- Returns:
- the
FormattingStyle
that will be used. - Since:
- 2.11.0
- See Also:
-
setLenient
Deprecated.Please usesetStrictness(Strictness)
instead.JsonWriter.setLenient(true)
should be replaced byJsonWriter.setStrictness(Strictness.LENIENT)
andJsonWriter.setLenient(false)
should be replaced byJsonWriter.setStrictness(Strictness.LEGACY_STRICT)
.
However, if you usedsetLenient(false)
before, you might preferStrictness.STRICT
now instead.Sets the strictness of this writer.- Parameters:
lenient
- whether this writer should be lenient. If true, the strictness is set toStrictness.LENIENT
. If false, the strictness is set toStrictness.LEGACY_STRICT
.- See Also:
-
isLenient
public boolean isLenient()Returns true if theStrictness
of this writer is equal toStrictness.LENIENT
.- See Also:
-
setStrictness
Configures how strict this writer is with regard to the syntax rules specified in RFC 8259. By default,Strictness.LEGACY_STRICT
is used.Strictness.STRICT
&Strictness.LEGACY_STRICT
- The behavior of these is currently identical. In these strictness modes, the writer only writes JSON in accordance with RFC 8259.
Strictness.LENIENT
- This mode relaxes the behavior of the writer to allow the writing of
NaNs
andinfinities
. It also allows writing multiple top level values.
- Parameters:
strictness
- the new strictness of this writer. May not benull
.- Since:
- 2.11.0
- See Also:
-
getStrictness
Returns the strictness of this writer.- Since:
- 2.11.0
- See Also:
-
setHtmlSafe
public final void setHtmlSafe(boolean htmlSafe) Configures 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.- See Also:
-
isHtmlSafe
public final boolean isHtmlSafe()Returns true if this writer writes JSON that's safe for inclusion in HTML and XML documents.- See Also:
-
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.- See Also:
-
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.- See Also:
-
beginArray
Begins encoding a new array. Each call to this method must be paired with a call toendArray()
.- Returns:
- this writer.
- Throws:
IOException
-
endArray
Ends encoding the current array.- Returns:
- this writer.
- Throws:
IOException
-
beginObject
Begins encoding a new object. Each call to this method must be paired with a call toendObject()
.- Returns:
- this writer.
- Throws:
IOException
-
endObject
Ends encoding the current object.- Returns:
- this writer.
- Throws:
IOException
-
openScope
Enters a new scope by appending any necessary whitespace and the given bracket.- Throws:
IOException
-
closeScope
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
Encodes the property name.- Parameters:
name
- the name of the forthcoming value. May not benull
.- Returns:
- this writer.
- Throws:
IOException
-
writeDeferredName
- Throws:
IOException
-
value
Encodesvalue
.- Parameters:
value
- the literal string value, or null to encode a null literal.- Returns:
- this writer.
- Throws:
IOException
-
value
Encodesvalue
.- Returns:
- this writer.
- Throws:
IOException
-
value
Encodesvalue
.- Returns:
- this writer.
- Throws:
IOException
- Since:
- 2.7
-
value
Encodesvalue
.- Parameters:
value
- a finite value, or iflenient
, alsoNaN
orinfinity
.- Returns:
- this writer.
- Throws:
IllegalArgumentException
- if the value is NaN or Infinity and this writer is notlenient
.IOException
- Since:
- 2.9.1
-
value
Encodesvalue
.- Parameters:
value
- a finite value, or iflenient
, alsoNaN
orinfinity
.- Returns:
- this writer.
- Throws:
IllegalArgumentException
- if the value is NaN or Infinity and this writer is notlenient
.IOException
-
value
Encodesvalue
.- Returns:
- this writer.
- Throws:
IOException
-
value
Encodesvalue
. The value is written by directly writing theObject.toString()
result to JSON. Implementations must make sure that the result represents a valid JSON number.- Parameters:
value
- a finite value, or iflenient
, alsoNaN
orinfinity
.- Returns:
- this writer.
- Throws:
IllegalArgumentException
- if the value is NaN or Infinity and this writer is notlenient
; or if thetoString()
result is not a valid JSON number.IOException
-
nullValue
Encodesnull
.- Returns:
- this writer.
- Throws:
IOException
-
jsonValue
Writesvalue
directly to the writer without quoting or escaping. This might not be supported by all implementations, if not supported anUnsupportedOperationException
is thrown.- Parameters:
value
- the literal string value, or null to encode a null literal.- Returns:
- this writer.
- Throws:
UnsupportedOperationException
- if this writer does not support writing raw JSON values.IOException
- Since:
- 2.4
-
flush
Ensures all buffered data is written to the underlyingWriter
and flushes that writer.- Specified by:
flush
in interfaceFlushable
- Throws:
IOException
-
close
Flushes and closes this writer and the underlyingWriter
.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- if the JSON document is incomplete.
-
alwaysCreatesValidJsonNumber
Returns whether thetoString()
ofc
will always return a valid JSON number. -
string
- Throws:
IOException
-
newline
- Throws:
IOException
-
beforeName
Inserts any necessary separators and whitespace before a name. Also adjusts the stack to expect the name's value.- Throws:
IOException
-
beforeValue
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.- Throws:
IOException
-
setStrictness(Strictness)
instead.