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, toString
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
compute, computeIfAbsent, computeIfPresent, forEach, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll
public 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.name
public 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.3 - Copyright © 2003-2021 The Apache Software Foundation.