public final class JSONObject extends JSONCollection implements Map<String,Object>
JSONObjects, JSONArrays, Strings, Booleans, Integers, Longs, Doubles or NULL.
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 NULL 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 RuntimeException if the requested name has no value
or if the value cannot be coerced to the requested type.
opt() to retrieve an optional value.
Warning: this class represents null in two incompatible
ways: the standard Java null reference, and the sentinel value NULL. 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.
| Modifier and Type | Field and Description |
|---|---|
static Object |
NULL
A sentinel value used to explicitly define a name with no value.
|
| Constructor and Description |
|---|
JSONObject()
Creates a
JSONObject with no name/value mappings. |
JSONObject(JSONObject copyFrom,
String... names)
Creates a new
JSONObject by copying mappings for the listed names
from the given object. |
JSONObject(Object... keysAndValues)
Constructs a new JSONObject using a series of String keys and object values.
|
JSONObject(String json)
Creates a new
JSONObject with name/value mappings from the JSON
string. |
| Modifier and Type | Method and Description |
|---|---|
JSONObject |
accumulate(String name,
Object value)
Appends
value to the array already mapped to name. |
JSONObject |
append(String name,
Object value)
Appends values to the array mapped to
name. |
void |
clear()
Removes all of the mappings from this JSONObject.
|
boolean |
containsKey(Object key)
Returns
true if this JSONObject contains a mapping for the specified
key. |
boolean |
containsValue(Object value)
Returns
true if this JSONObject maps one or more keys to the
specified value. |
JSONObject |
copy()
Returns a new JSONObject that is a shallow copy of this JSONObject.
|
Set<Map.Entry<String,Object>> |
entrySet()
Returns a
Set view of the mappings contained in this JSONObject. |
boolean |
equals(Object obj) |
Object |
get(Object name)
Returns the value mapped by
name, or throws if no such mapping exists. |
boolean |
getBoolean(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. |
boolean |
getBooleanOrDefault(String name,
boolean defaultValue)
Returns the value to which the specified key is mapped and a boolean, or
defaultValue if this JSONObject contains no mapping for the key. |
double |
getDouble(String name)
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or throws otherwise. |
int |
getInt(String name)
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or throws otherwise. |
int |
getIntOrDefault(String name,
int defaultValue)
Returns the value to which the specified key is mapped and an int, or
defaultValue if this JSONObject contains no mapping for the key. |
JSONArray |
getJSONArray(String name)
Returns the value mapped by
name if it exists and is a JSONArray, or throws otherwise. |
JSONArray |
getJSONArrayOrDefault(String name,
JSONArray defaultValue)
Returns the value to which the specified key is mapped and a JSONArray, or
defaultValue if this JSONObject contains no mapping for the key. |
JSONObject |
getJSONObject(String name)
Returns the value mapped by
name if it exists and is a JSONObject, or throws otherwise. |
JSONObject |
getJSONObjectOrDefault(String name,
JSONObject defaultValue)
Returns the value to which the specified key is mapped and a JSONObject, or
defaultValue if this map contains no mapping for the key. |
long |
getLong(String name)
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or throws otherwise. |
long |
getLongOrDefault(String name,
int defaultValue)
Returns the value to which the specified key is mapped and a long, or
defaultValue if this JSONObject contains no mapping for the key. |
Object |
getOrDefault(Object key,
Object defaultValue)
Returns the value to which the specified key is mapped, or
defaultValue if this JSONObject contains no mapping for the key. |
String |
getString(String name)
Returns the value mapped by
name if it exists, coercing it if
necessary, or throws if no such mapping exists. |
String |
getStringOrDefault(String name,
String defaultValue)
Returns the value to which the specified key is mapped and a string, or
defaultValue if this JSONObject contains no mapping for the key. |
boolean |
has(String name)
Deprecated.
use
containsKey(Object) instead |
JSONObject |
in(String key)
Navigates into a nested JSONObject, creating the JSONObject if necessary.
|
boolean |
isEmpty()
Returns
true if this JSONObject contains no key-value mappings. |
boolean |
isNull(String name)
Returns true if this object has no mapping for
name or if it has
a mapping whose value is NULL. |
Set<String> |
keys()
Returns the set of
String names in this object. |
Set<String> |
keySet()
Returns a
Set view of the keys contained in this JSONObject. |
int |
length()
Deprecated.
Use
size() instead. |
JSONArray |
names()
Returns an array containing the string names in this object.
|
static String |
numberToString(Number number)
Encodes the number as a JSON string.
|
Object |
opt(Object name)
Returns the value mapped by
name, or null if no such mapping
exists. |
JSONObject |
put(String name,
Object value)
Maps
name to value, clobbering any existing name/value
mapping with the same name. |
void |
putAll(Map<? extends String,? extends Object> newProperties)
Invokes
put(String, Object) for each value from the map. |
static String |
quote(String data)
Encodes
data as a JSON string. |
Object |
remove(Object name)
Removes the named mapping if it exists; does nothing otherwise.
|
int |
size()
Returns the number of key-value mappings in this JSONObject.
|
Map<String,Object> |
toMap()
Returns a Map of the keys and values of the JSONObject.
|
Collection<Object> |
values()
Returns a
Collection view of the values contained in this JSONObject. |
prettyPrint, print, print, toCompactString, toString, toStringclone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitcompute, computeIfAbsent, computeIfPresent, forEach, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAllpublic static final Object NULL
null, names with this value:
names() array
keys() iterator
true for has(String)
get(java.lang.Object)
This value violates the general contract of Object.equals(java.lang.Object) by
returning true when compared to null. Its JSONCollection.toString()
method returns "null".
public JSONObject()
JSONObject with no name/value mappings.public JSONObject(String json)
JSONObject with name/value mappings from the JSON
string.json - a JSON-encoded string containing an object.RuntimeException - if the parse fails or doesn't yield a JSONObject.public JSONObject(JSONObject copyFrom, String... names)
JSONObject by copying mappings for the listed names
from the given object. Names that aren't present in copyFrom will
be skipped.copyFrom - The source object.names - The names of the fields to copy.RuntimeException - On internal errors. Shouldn't happen.public JSONObject(Object... keysAndValues)
put(String, Object). Keys must be strings
(toString() will be invoked on each key).
Prior to release 5.4, keysAndValues was type String...; changing it to Object... makes
it much easier to initialize a JSONObject in a single statement, which is more readable.public JSONObject copy()
@Deprecated public int length()
size() instead.public JSONObject put(String name, Object value)
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.put in interface Map<String,Object>name - The name of the new value.value - a JSONObject, JSONArray, String, Boolean,
Integer, Long, Double, NULL, or null. May not be
NaNs or infinities.IllegalArgumentException - if the value is an invalid double (infinite or NaN).public JSONObject accumulate(String name, Object value)
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.name - The name of the field to change.value - a JSONObject, JSONArray, String, Boolean,
Integer, Long, Double, NULL or null. May not be NaNs or infinities.RuntimeException - If the object being added is an invalid number.public JSONObject append(String name, Object value)
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 RuntimeException
will be thrown.name - The name of the array to which the value should be appended.value - The value to append.JSONTypeMismatchException - if name is null or if the mapping for
name is non-null and is not a JSONArray.public boolean isNull(String name)
name or if it has
a mapping whose value is NULL.name - The name of the value to check on.@Deprecated public boolean has(String name)
containsKey(Object) insteadname. The mapping
may be NULL.name - The name of the value to check on.namepublic Object opt(Object name)
name, or null if no such mapping
exists.name - The name of the value to get.public boolean getBoolean(String name)
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise.name - The name of the field we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping cannot be coerced
to a boolean.public boolean getBooleanOrDefault(String name, boolean defaultValue)
defaultValue if this JSONObject contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to a boolean.public double getDouble(String name)
name if it exists and is a double or
can be coerced to a double, or throws otherwise.name - The name of the field we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping cannot be coerced
to a double.public int getInt(String name)
name if it exists and is an int or
can be coerced to an int, or throws otherwise.name - The name of the field we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping cannot be coerced
to an int.public int getIntOrDefault(String name, int defaultValue)
defaultValue if this JSONObject contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to an int.public long getLong(String name)
name if it exists and is a long or
can be coerced to a long, or throws otherwise.
Note that JSON represents numbers as doubles,
so this is lossy; use strings to transfer numbers
via JSON without loss.name - The name of the field that we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping cannot be coerced
to a long.public long getLongOrDefault(String name, int defaultValue)
defaultValue if this JSONObject contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to a long.public String getString(String name)
name if it exists, coercing it if
necessary, or throws if no such mapping exists.name - The name of the field we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping cannot be coerced
to Stringpublic String getStringOrDefault(String name, String defaultValue)
defaultValue if this JSONObject contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to a string.public JSONArray getJSONArray(String name)
name if it exists and is a JSONArray, or throws otherwise.name - The field we want to get.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping is not a JSONArray.public JSONArray getJSONArrayOrDefault(String name, JSONArray defaultValue)
defaultValue if this JSONObject contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to a JSONArray.public JSONObject getJSONObject(String name)
name if it exists and is a JSONObject, or throws otherwise.name - The name of the field that we want.JSONValueNotFoundException - if the mapping doesn't existJSONTypeMismatchException - if the mapping is not a JSONObject.public JSONObject getJSONObjectOrDefault(String name, JSONObject defaultValue)
defaultValue if this map contains no mapping for the key.name - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this map contains no mapping for the keyJSONTypeMismatchException - if the mapping cannot be coerced
to a JSONObject.public Set<String> keys()
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 JSONArray names()
public static String numberToString(Number number)
number - a finite value. May not be NaNs or
infinities.RuntimeException - On internal errors. Shouldn't happen.public static String quote(String data)
data as a JSON string. This applies quotes and any
necessary character escaping.data - the string to encode. Null will be interpreted as an empty
string.public Map<String,Object> toMap()
NULL in the map.public JSONObject in(String key)
key - IllegalStateException - if the current value for the key is not null and not JSONObjectpublic int size()
Integer.MAX_VALUE elements, returns
Integer.MAX_VALUE.public boolean isEmpty()
true if this JSONObject contains no key-value mappings.public boolean containsKey(Object key)
true if this JSONObject contains a mapping for the specified
key.containsKey in interface Map<String,Object>key - key whose presence in this map is to be testedtrue if this map contains a mapping for the specified
keypublic boolean containsValue(Object value)
true if this JSONObject maps one or more keys to the
specified value.containsValue in interface Map<String,Object>value - value whose presence in this map is to be testedtrue if this JSONObject maps one or more keys to the
specified valuepublic Object get(Object name)
name, or throws if no such mapping exists.get in interface Map<String,Object>name - The name of the value to get.JSONValueNotFoundException - if no such mapping exists.public Object getOrDefault(Object key, Object defaultValue)
defaultValue if this JSONObject contains no mapping for the key.getOrDefault in interface Map<String,Object>key - the key whose associated value is to be returneddefaultValue - the default mapping of the keydefaultValue if this JSONObject contains no mapping for the keypublic Object remove(Object name)
public void putAll(Map<? extends String,? extends Object> newProperties)
put(String, Object) for each value from the map.public void clear()
public Set<String> keySet()
Set view of the keys contained in this JSONObject.
The set is backed by the JSONObject, so changes to the map are
reflected in the set, and vice-versa.public Collection<Object> values()
Collection view of the values contained in this JSONObject.
The collection is backed by the JSONObject, so changes to the map are
reflected in the collection, and vice-versa.5.6.4 - Copyright © 2003-2021 The Apache Software Foundation.