public final class JsonObject extends JsonElement implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,JsonElement>>, Freezable<JsonObject>
JsonObjects, JsonArrays, Strings, Booleans, Integers, Longs, Doubles or JsonNull.
Values may not be null, NaNs, infinities, or of any type not listed here.
This class can coerce values to another type when requested.
Number types will
be coerced using doubleValue. Strings
that can be coerced using Double.valueOf(String) will be.
Number types will
be coerced using intValue. Strings
that can be coerced using Double.valueOf(String) will be,
and then cast to int.
Number types will
be coerced using longValue. Strings
that can be coerced using Double.valueOf(String) will be,
and then cast to long. This two-step conversion is lossy for very
large values. For example, the string "9223372036854775806" yields the
long 9223372036854775807.
String.valueOf(Object). Although null cannot be
coerced, the sentinel value JsonNull is coerced to the
string "null".
This class can look up both mandatory and optional values:
getType() to retrieve a mandatory value. This
fails with a JsonException if the requested name has no value
or if the value cannot be coerced to the requested type.
optType() to retrieve an optional value. This
returns a system- or user-supplied default if the requested name has no
value or if the value cannot be coerced to the requested type.
Warning: this class represents null in two incompatible
ways: the standard Java null reference, and the sentinel value JsonNull. In particular, calling put(name, null) removes the
named entry from the object but put(name, JsonObject.NULL) stores an
entry whose value is JsonObject.NULL.
Instances of this class are not thread safe. Although this class is nonfinal, it was not designed for inheritance and should not be subclassed. In particular, self-use by overrideable methods is not specified. See Effective Java Item 17, "Design and Document or inheritance or else prohibit it" for further information.
| Constructor and Description |
|---|
JsonObject()
Creates a
JsonObject with no name/value mappings. |
JsonObject(java.util.Map copyFrom)
Creates a new
JSONObject by copying all name/value mappings from
the given map. |
| Modifier and Type | Method and Description |
|---|---|
JsonObject |
accumulate(java.lang.String name,
java.lang.Object value)
Appends
value to the array already mapped to name. |
JsonObject |
append(java.lang.String name,
java.lang.Object value)
Appends values to the array mapped to
name. |
JsonObject |
asJsonObject() |
void |
checkIfFrozen() |
JsonObject |
clear() |
JsonObject |
cloneAsThawed()
Provides for the clone operation.
|
boolean |
equals(java.lang.Object o) |
JsonObject |
freeze()
Freezes the object.
|
JsonElement |
get(java.lang.String name)
Returns the value mapped by
name, or throws if no such mapping exists. |
java.lang.Boolean |
getBoolean(java.lang.String name)
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise. |
java.lang.Boolean |
getBoolean(java.lang.String name,
boolean strict)
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise. |
java.lang.Double |
getDouble(java.lang.String name) |
java.lang.Double |
getDouble(java.lang.String name,
boolean strict)
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or throws otherwise. |
java.lang.Integer |
getInt(java.lang.String name) |
java.lang.Integer |
getInt(java.lang.String name,
boolean strict)
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or throws otherwise. |
JsonArray |
getJsonArray(java.lang.String name)
Returns the value mapped by
name if it exists and is a JsonArray, or throws otherwise. |
JsonObject |
getJsonObject(java.lang.String name)
Returns the value mapped by
name if it exists and is a JsonObject, or throws otherwise. |
java.lang.String |
getJsonType() |
java.lang.Long |
getLong(java.lang.String name) |
java.lang.Long |
getLong(java.lang.String name,
boolean strict)
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or throws otherwise. |
java.lang.String |
getString(java.lang.String name) |
java.lang.String |
getString(java.lang.String name,
boolean strict)
Returns the value mapped by
name if it exists, coercing it if
necessary, or throws if no such mapping exists. |
boolean |
has(java.lang.String name)
Returns true if this object has a mapping for
name. |
boolean |
isFrozen()
Determines whether the object has been frozen or not.
|
boolean |
isJsonObject() |
boolean |
isNull(java.lang.String name)
Returns true if this object has no mapping for
name or if it has
a mapping whose value is JsonNull. |
java.util.Iterator<java.util.Map.Entry<java.lang.String,JsonElement>> |
iterator() |
java.util.Iterator<java.lang.String> |
keys()
Returns an iterator of the
String names in this object. |
java.util.Set<java.lang.String> |
keySet()
Returns the set of
String names in this object. |
int |
length()
Returns the number of name/value mappings in this object.
|
JsonObject |
merge(JsonObject another)
Merge Json Object with another Json Object.
|
JsonArray |
names()
Returns an array containing the string names in this object.
|
JsonElement |
opt(java.lang.String name)
Returns the value mapped by
name, or null if no such mapping
exists. |
java.lang.Boolean |
optBoolean(java.lang.String name)
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or false otherwise. |
java.lang.Boolean |
optBoolean(java.lang.String name,
java.lang.Boolean fallback)
Returns the value mapped by
name if it exists and is a boolean
or fallback otherwise. |
java.lang.Boolean |
optBoolean(java.lang.String name,
java.lang.Boolean fallback,
boolean strict) |
java.lang.Double |
optDouble(java.lang.String name)
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or NaN otherwise. |
java.lang.Double |
optDouble(java.lang.String name,
java.lang.Double fallback)
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or fallback otherwise. |
java.lang.Double |
optDouble(java.lang.String name,
java.lang.Double fallback,
boolean strict) |
java.lang.Integer |
optInt(java.lang.String name)
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or 0 otherwise. |
java.lang.Integer |
optInt(java.lang.String name,
java.lang.Integer fallback)
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or fallback otherwise. |
java.lang.Integer |
optInt(java.lang.String name,
java.lang.Integer fallback,
boolean strict) |
JsonArray |
optJsonArray(java.lang.String name)
Returns the value mapped by
name if it exists and is a JsonArray, or null otherwise. |
JsonObject |
optJsonObject(java.lang.String name)
Returns the value mapped by
name if it exists and is a JsonObject, or null otherwise. |
java.lang.Long |
optLong(java.lang.String name)
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or 0 otherwise. |
java.lang.Long |
optLong(java.lang.String name,
java.lang.Long fallback)
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or fallback otherwise. |
java.lang.Long |
optLong(java.lang.String name,
java.lang.Long fallback,
boolean strict) |
java.lang.String |
optString(java.lang.String name)
Returns the value mapped by
name if it exists, coercing it if
necessary, or the empty string if no such mapping exists. |
java.lang.String |
optString(java.lang.String name,
java.lang.String fallback)
Returns the value mapped by
name if it exists, coercing it if
necessary, or fallback if no such mapping exists. |
java.lang.String |
optString(java.lang.String name,
java.lang.String fallback,
boolean strict) |
JsonObject |
put(java.lang.String name,
boolean value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
put(java.lang.String name,
double value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
put(java.lang.String name,
int value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
put(java.lang.String name,
JsonElement value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
put(java.lang.String name,
long value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
put(java.lang.String name,
java.lang.Object value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
JsonObject |
putOpt(java.lang.String name,
java.lang.Object value)
Equivalent to
put(name, value) when both parameters are non-null;
does nothing otherwise. |
java.lang.Object |
remove(java.lang.String name)
Removes the named mapping if it exists; does nothing otherwise.
|
JsonArray |
toJsonArray(JsonArray names)
Returns an array with the values corresponding to
names. |
java.util.Collection<JsonElement> |
valuesSet() |
void |
write(JsonWriter writer) |
public JsonObject()
JsonObject with no name/value mappings.public JsonObject(java.util.Map copyFrom)
throws JsonException
JSONObject by copying all name/value mappings from
the given map.copyFrom - a map whose keys are of type String and whose
values are of supported types.java.lang.NullPointerException - if any of the map's keys are null.JsonExceptionpublic int length()
public JsonObject put(java.lang.String name, boolean value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name.JsonExceptionpublic JsonObject put(java.lang.String name, double value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name.value - a finite value. May not be NaNs or
infinities.JsonExceptionpublic JsonObject put(java.lang.String name, int value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name.JsonExceptionpublic JsonObject put(java.lang.String name, long value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name.JsonExceptionpublic JsonObject put(java.lang.String name, java.lang.Object value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name. If the value is null, any existing
mapping for name is removed.value - a JsonObject, JsonArray, String, Boolean,
Integer, Long, Double, null. May not be
NaNs or infinities.JsonExceptionpublic JsonObject put(java.lang.String name, JsonElement value) throws JsonException
name to value, clobbering any existing name/value
mapping with the same name. If the value is null, any existing
mapping for name is removed.value - a JsonObject, JsonArray, JsonString, JsonBoolean,
JsonNumber, JsonNull. May not be
NaNs or infinities.JsonExceptionpublic JsonObject putOpt(java.lang.String name, java.lang.Object value) throws JsonException
put(name, value) when both parameters are non-null;
does nothing otherwise.JsonExceptionpublic JsonObject accumulate(java.lang.String name, java.lang.Object value) throws JsonException
value to the array already mapped to name. If
this object has no mapping for name, this inserts a new mapping.
If the mapping exists but its value is not an array, the existing
and new values are inserted in order into a new array which is itself
mapped to name. In aggregate, this allows values to be added to a
mapping one at a time.
Note that append(String, Object) provides better semantics.
In particular, the mapping for name will always be a
JsonArray. Using accumulate will result in either a
JsonArray or a mapping whose type is the type of value
depending on the number of calls to it.
value - a JsonObject, JsonArray, String, Boolean,
Integer, Long, Double or null. May not be NaNs or infinities.JsonExceptionpublic JsonObject append(java.lang.String name, java.lang.Object value) throws JsonException
name. A new JsonArray
mapping for name will be inserted if no mapping exists. If the existing
mapping for name is not a JsonArray, a JsonException
will be thrown.JsonException - if name is null or if the mapping for
name is non-null and is not a JsonArray.public java.lang.Object remove(java.lang.String name)
name, or null if there was
no such mapping.public boolean isNull(java.lang.String name)
name or if it has
a mapping whose value is JsonNull.public boolean has(java.lang.String name)
name. The mapping
may be JsonNull.public JsonElement get(java.lang.String name) throws JsonException
name, or throws if no such mapping exists.JsonException - if no such mapping exists.public JsonElement opt(java.lang.String name)
name, or null if no such mapping
exists.public java.lang.Boolean getBoolean(java.lang.String name,
boolean strict)
throws JsonException
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise.JsonException - if the mapping doesn't exist or cannot be coerced
to a boolean.public java.lang.Boolean getBoolean(java.lang.String name)
throws JsonException
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise.JsonException - if the mapping doesn't exist or cannot be coerced
to a boolean.public java.lang.Boolean optBoolean(java.lang.String name)
name if it exists and is a boolean or
can be coerced to a boolean, or false otherwise.public java.lang.Boolean optBoolean(java.lang.String name,
java.lang.Boolean fallback)
name if it exists and is a boolean
or fallback otherwise.public java.lang.Boolean optBoolean(java.lang.String name,
java.lang.Boolean fallback,
boolean strict)
public java.lang.Double getDouble(java.lang.String name,
boolean strict)
throws JsonException
name if it exists and is a double or
can be coerced to a double, or throws otherwise.JsonException - if the mapping doesn't exist or cannot be coerced
to a double.public java.lang.Double getDouble(java.lang.String name)
throws JsonException
JsonExceptionpublic java.lang.Double optDouble(java.lang.String name)
name if it exists and is a double or
can be coerced to a double, or NaN otherwise.public java.lang.Double optDouble(java.lang.String name,
java.lang.Double fallback)
name if it exists and is a double or
can be coerced to a double, or fallback otherwise.public java.lang.Double optDouble(java.lang.String name,
java.lang.Double fallback,
boolean strict)
public java.lang.Integer getInt(java.lang.String name,
boolean strict)
throws JsonException
name if it exists and is an int or
can be coerced to an int, or throws otherwise.JsonException - if the mapping doesn't exist or cannot be coerced
to an int.public java.lang.Integer getInt(java.lang.String name)
throws JsonException
JsonExceptionpublic java.lang.Integer optInt(java.lang.String name)
name if it exists and is an int or
can be coerced to an int, or 0 otherwise.public java.lang.Integer optInt(java.lang.String name,
java.lang.Integer fallback)
name if it exists and is an int or
can be coerced to an int, or fallback otherwise.public java.lang.Integer optInt(java.lang.String name,
java.lang.Integer fallback,
boolean strict)
public java.lang.Long getLong(java.lang.String name,
boolean strict)
throws JsonException
name if it exists and is a long or
can be coerced to a long, or throws otherwise.
Note that Util represents numbers as doubles,
so this is lossy; use strings to transfer numbers via Util.JsonException - if the mapping doesn't exist or cannot be coerced
to a long.public java.lang.Long getLong(java.lang.String name)
throws JsonException
JsonExceptionpublic java.lang.Long optLong(java.lang.String name)
name if it exists and is a long or
can be coerced to a long, or 0 otherwise. Note that Util represents numbers as doubles,
so this is lossy; use strings to transfer numbers via Util.public java.lang.Long optLong(java.lang.String name,
java.lang.Long fallback)
name if it exists and is a long or
can be coerced to a long, or fallback otherwise. Note that Util represents
numbers as doubles, so this is lossy; use strings to transfer
numbers via Util.public java.lang.Long optLong(java.lang.String name,
java.lang.Long fallback,
boolean strict)
public java.lang.String getString(java.lang.String name,
boolean strict)
throws JsonException
name if it exists, coercing it if
necessary, or throws if no such mapping exists.JsonException - if no such mapping exists.public java.lang.String getString(java.lang.String name)
throws JsonException
JsonExceptionpublic java.lang.String optString(java.lang.String name)
name if it exists, coercing it if
necessary, or the empty string if no such mapping exists.public java.lang.String optString(java.lang.String name,
java.lang.String fallback)
name if it exists, coercing it if
necessary, or fallback if no such mapping exists.public java.lang.String optString(java.lang.String name,
java.lang.String fallback,
boolean strict)
public JsonArray getJsonArray(java.lang.String name) throws JsonException
name if it exists and is a JsonArray, or throws otherwise.JsonException - if the mapping doesn't exist or is not a JsonArray.public JsonArray optJsonArray(java.lang.String name)
name if it exists and is a JsonArray, or null otherwise.public JsonObject getJsonObject(java.lang.String name) throws JsonException
name if it exists and is a JsonObject, or throws otherwise.JsonException - if the mapping doesn't exist or is not a JsonObject.public JsonObject optJsonObject(java.lang.String name)
name if it exists and is a JsonObject, or null otherwise.public JsonArray toJsonArray(JsonArray names) throws JsonException
names. The
array contains null for names that aren't mapped. This method returns
null if names is either null or empty.JsonExceptionpublic java.util.Iterator<java.lang.String> keys()
String names in this object. The
returned iterator supports remove, which will
remove the corresponding mapping from this object. If this object is
modified after the iterator is returned, the iterator's behavior is
undefined. The order of the keys is undefined.public java.util.Set<java.lang.String> keySet()
String names in this object. The returned set
is a view of the keys in this object. Set.remove(Object) will remove
the corresponding mapping from this object and set iterator behaviour
is undefined if this object is modified after it is returned.
See keys().public java.util.Collection<JsonElement> valuesSet()
public JsonArray names() throws JsonException
JsonExceptionpublic void write(JsonWriter writer) throws java.io.IOException
write in class JsonElementjava.io.IOExceptionpublic boolean isJsonObject()
isJsonObject in class JsonElementpublic JsonObject asJsonObject()
asJsonObject in class JsonElementpublic boolean equals(java.lang.Object o)
equals in class JsonElementpublic java.lang.String getJsonType()
getJsonType in class JsonElementpublic java.util.Iterator<java.util.Map.Entry<java.lang.String,JsonElement>> iterator()
iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,JsonElement>>public JsonObject merge(JsonObject another)
another - public JsonObject clear()
public boolean isFrozen()
FreezableisFrozen in interface Freezable<JsonObject>public JsonObject freeze()
Freezablefreeze in interface Freezable<JsonObject>public JsonObject cloneAsThawed()
FreezablecloneAsThawed in interface Freezable<JsonObject>public void checkIfFrozen()