public abstract class JsonWriter extends Object implements Closeable, Flushable
JsonWriter
. Each JSON
document must contain one top-level array or object. Call methods on the
writer as you walk the structure's contents, nesting arrays and objects as
necessary:
beginArray()
.
Write each of the array's elements with the appropriate value(java.lang.String)
methods or by nesting other arrays and objects. Finally close the array
using endArray()
.
beginObject()
.
Write each of the object's properties by alternating calls to
name(java.lang.String)
with the property's value. Write property values with the
appropriate value(java.lang.String)
method or by nesting other objects or arrays.
Finally close the object using endObject()
.
[
{
"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(BufferedSink sink, List<Message> messages) throws IOException {
JsonWriter writer = JsonWriter.of(sink);
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
.
Modifier and Type | Method and Description |
---|---|
abstract JsonWriter |
beginArray()
Begins encoding a new array.
|
int |
beginFlatten()
Cancels immediately-nested calls to
beginArray() or beginObject() and their
matching calls to endArray() or endObject() . |
abstract JsonWriter |
beginObject()
Begins encoding a new object.
|
abstract JsonWriter |
endArray()
Ends encoding the current array.
|
void |
endFlatten(int token)
Ends nested call flattening created by
beginFlatten() . |
abstract JsonWriter |
endObject()
Ends encoding the current object.
|
String |
getIndent()
Returns a string containing only whitespace, used for each level of
indentation.
|
String |
getPath()
Returns a JsonPath to
the current location in the JSON value.
|
boolean |
getSerializeNulls()
Returns true if object members are serialized when their value is null.
|
boolean |
isLenient()
Returns true if this writer has relaxed syntax rules.
|
abstract JsonWriter |
name(String name)
Encodes the property name.
|
abstract JsonWriter |
nullValue()
Encodes
null . |
static JsonWriter |
of(okio.BufferedSink sink)
Returns a new instance that writes UTF-8 encoded JSON to
sink . |
void |
setIndent(String indent)
Sets the indentation string to be repeated for each level of indentation
in the encoded document.
|
void |
setLenient(boolean lenient)
Configure this writer to relax its syntax rules.
|
void |
setSerializeNulls(boolean serializeNulls)
Sets whether object members are serialized when their value is null.
|
abstract JsonWriter |
value(boolean value)
Encodes
value . |
abstract JsonWriter |
value(Boolean value)
Encodes
value . |
abstract JsonWriter |
value(okio.BufferedSource source)
Writes
source directly without encoding its contents. |
abstract JsonWriter |
value(double value)
Encodes
value . |
abstract JsonWriter |
value(long value)
Encodes
value . |
abstract JsonWriter |
value(Number value)
Encodes
value . |
abstract JsonWriter |
value(String value)
Encodes
value . |
@CheckReturnValue public static JsonWriter of(okio.BufferedSink sink)
sink
.public void setIndent(String indent)
indent.isEmpty()
the encoded document
will be compact. Otherwise the encoded document will be more
human-readable.indent
- a string containing only whitespace.@CheckReturnValue public final String getIndent()
public final void setLenient(boolean lenient)
@CheckReturnValue public final boolean isLenient()
public final void setSerializeNulls(boolean serializeNulls)
@CheckReturnValue public final boolean getSerializeNulls()
public abstract JsonWriter beginArray() throws IOException
endArray()
.IOException
public abstract JsonWriter endArray() throws IOException
IOException
public abstract JsonWriter beginObject() throws IOException
endObject()
.IOException
public abstract JsonWriter endObject() throws IOException
IOException
public abstract JsonWriter name(String name) throws IOException
name
- the name of the forthcoming value. Must not be null.IOException
public abstract JsonWriter value(@Nullable String value) throws IOException
value
.value
- the literal string value, or null to encode a null literal.IOException
public abstract JsonWriter nullValue() throws IOException
null
.IOException
public abstract JsonWriter value(boolean value) throws IOException
value
.IOException
public abstract JsonWriter value(@Nullable Boolean value) throws IOException
value
.IOException
public abstract JsonWriter value(double value) throws IOException
value
.value
- a finite value. May not be NaNs or
infinities.IOException
public abstract JsonWriter value(long value) throws IOException
value
.IOException
public abstract JsonWriter value(@Nullable Number value) throws IOException
value
.value
- a finite value. May not be NaNs or
infinities.IOException
public abstract JsonWriter value(okio.BufferedSource source) throws IOException
source
directly without encoding its contents.
Since no validation is performed, setSerializeNulls(boolean)
and other writer configurations
are not respected.IOException
@CheckReturnValue public final int beginFlatten()
beginArray()
or beginObject()
and their
matching calls to endArray()
or endObject()
. Use this to compose JSON adapters
without nesting.
For example, the following creates JSON with nested arrays: [1,[2,3,4],5]
.
JsonAdapter<List<Integer>> integersAdapter = ...
public void writeNumbers(JsonWriter writer) {
writer.beginArray();
writer.value(1);
integersAdapter.toJson(writer, Arrays.asList(2, 3, 4));
writer.value(5);
writer.endArray();
}
With flattening we can create JSON with a single array [1,2,3,4,5]
:
JsonAdapter<List<Integer>> integersAdapter = ...
public void writeNumbers(JsonWriter writer) {
writer.beginArray();
int token = writer.beginFlatten();
writer.value(1);
integersAdapter.toJson(writer, Arrays.asList(2, 3, 4));
writer.value(5);
writer.endFlatten(token);
writer.endArray();
}
This method flattens arrays within arrays:
Emit: [1, [2, 3, 4], 5]
To produce: [1, 2, 3, 4, 5]
It also flattens objects within objects. Do not call name(java.lang.String)
before writing a flattened
object.
Emit: {"a": 1, {"b": 2}, "c": 3}
To Produce: {"a": 1, "b": 2, "c": 3}
Other combinations are permitted but do not perform flattening. For example, objects inside of
arrays are not flattened:
Emit: [1, {"b": 2}, 3, [4, 5], 6]
To Produce: [1, {"b": 2}, 3, 4, 5, 6]
This method returns an opaque token. Callers must match all calls to this method with a call
to endFlatten(int)
with the matching token.
public final void endFlatten(int token)
beginFlatten()
.@CheckReturnValue public final String getPath()
Copyright © 2018. All rights reserved.