java.lang.Object | |
↳ | org.json.JSONObject |
A modifiable set of name/value mappings. Names are unique, non-null strings.
Values may be any mix of 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 valueOf(String)
will be.
Number
types will
be coerced using intValue
. Strings
that can be coerced using valueOf(String)
will be,
and then cast to int.
Number
types will
be coerced using longValue
. Strings
that can be coerced using 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.
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 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 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. 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.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
NULL | A sentinel value used to explicitly define a name with no value. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a
JSONObject with no name/value mappings. | |||||||||||
Creates a new
JSONObject by copying all name/value mappings from
the given map. | |||||||||||
Creates a new
JSONObject with name/value mappings from the next
object in the tokener. | |||||||||||
Creates a new
JSONObject with name/value mappings from the JSON
string. | |||||||||||
Creates a new
JSONObject by copying mappings for the listed names
from the given object. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Appends
value to the array already mapped to name . | |||||||||||
Returns the value mapped by
name , or throws if no such mapping exists. | |||||||||||
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a JSONArray , or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a JSONObject , or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or throws otherwise. | |||||||||||
Returns the value mapped by
name if it exists, coercing it if
necessary, or throws if no such mapping exists. | |||||||||||
Returns true if this object has a mapping for
name . | |||||||||||
Returns true if this object has no mapping for
name or if it has
a mapping whose value is NULL . | |||||||||||
Returns an iterator of the
String names in this object. | |||||||||||
Returns the number of name/value mappings in this object.
| |||||||||||
Returns an array containing the string names in this object.
| |||||||||||
Encodes the number as a JSON string.
| |||||||||||
Returns the value mapped by
name , or null if no such mapping
exists. | |||||||||||
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or false otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a boolean or
can be coerced to a boolean, or fallback otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or fallback otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a double or
can be coerced to a double, or NaN otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or fallback otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is an int or
can be coerced to an int, or 0 otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a JSONArray , or null otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a JSONObject , or null otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or 0 otherwise. | |||||||||||
Returns the value mapped by
name if it exists and is a long or
can be coerced to a long, or fallback otherwise. | |||||||||||
Returns the value mapped by
name if it exists, coercing it if
necessary, or the empty string if no such mapping exists. | |||||||||||
Returns the value mapped by
name if it exists, coercing it if
necessary, or fallback if no such mapping exists. | |||||||||||
Maps
name to value , clobbering any existing name/value
mapping with the same name. | |||||||||||
Maps
name to value , clobbering any existing name/value
mapping with the same name. | |||||||||||
Maps
name to value , clobbering any existing name/value
mapping with the same name. | |||||||||||
Maps
name to value , clobbering any existing name/value
mapping with the same name. | |||||||||||
Maps
name to value , clobbering any existing name/value
mapping with the same name. | |||||||||||
Equivalent to
put(name, value) when both parameters are non-null;
does nothing otherwise. | |||||||||||
Encodes
data as a JSON string. | |||||||||||
Removes the named mapping if it exists; does nothing otherwise.
| |||||||||||
Returns an array with the values corresponding to
names . | |||||||||||
Encodes this object as a compact JSON string, such as:
{"query":"Pizza","locations":[94043,90210]} | |||||||||||
Encodes this object as a human readable JSON string for debugging, such
as:
{ "query": "Pizza", "locations": [ 94043, 90210 ] } | |||||||||||
Wraps the given object if necessary.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
A sentinel value used to explicitly define a name with no value. Unlike
null
, names with this value:
names()
array
keys()
iterator
true
for has(String)
get(String)
This value violates the general contract of equals(Object)
by
returning true when compared to null
. Its toString()
method returns "null".
Creates a new 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. |
---|
NullPointerException | if any of the map's keys are null. |
---|
Creates a new JSONObject
with name/value mappings from the next
object in the tokener.
readFrom | a tokener whose nextValue() method will yield a
JSONObject . |
---|
JSONException | if the parse fails or doesn't yield a
JSONObject .
|
---|
Creates a new JSONObject
with name/value mappings from the JSON
string.
json | a JSON-encoded string containing an object. |
---|
JSONException | if the parse fails or doesn't yield a JSONObject .
|
---|
Creates a new JSONObject
by copying mappings for the listed names
from the given object. Names that aren't present in copyFrom
will
be skipped.
JSONException |
---|
Appends 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, NULL or null. May not be NaNs or infinities .
|
---|
JSONException |
---|
Returns the value mapped by name
, or throws if no such mapping exists.
JSONException | if no such mapping exists. |
---|
Returns the value mapped by 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. |
---|
Returns the value mapped by 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. |
---|
Returns the value mapped by 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. |
---|
Returns the value mapped by name
if it exists and is a JSONArray
, or throws otherwise.
JSONException | if the mapping doesn't exist or is not a JSONArray .
|
---|
Returns the value mapped by name
if it exists and is a JSONObject
, or throws otherwise.
JSONException | if the mapping doesn't exist or is not a JSONObject .
|
---|
Returns the value mapped by 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.
JSONException | if the mapping doesn't exist or cannot be coerced to a long. |
---|
Returns the value mapped by name
if it exists, coercing it if
necessary, or throws if no such mapping exists.
JSONException | if no such mapping exists. |
---|
Returns true if this object has a mapping for name
. The mapping
may be NULL
.
Returns true if this object has no mapping for name
or if it has
a mapping whose value is NULL
.
Returns an iterator of the 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.
Returns an array containing the string names in this object. This method returns null if this object contains no mappings.
Encodes the number as a JSON string.
number | a finite value. May not be NaNs or
infinities .
|
---|
JSONException |
---|
Returns the value mapped by name
, or null if no such mapping
exists.
Returns the value mapped by name
if it exists and is a boolean or
can be coerced to a boolean, or false otherwise.
Returns the value mapped by name
if it exists and is a boolean or
can be coerced to a boolean, or fallback
otherwise.
Returns the value mapped by name
if it exists and is a double or
can be coerced to a double, or fallback
otherwise.
Returns the value mapped by name
if it exists and is a double or
can be coerced to a double, or NaN
otherwise.
Returns the value mapped by name
if it exists and is an int or
can be coerced to an int, or fallback
otherwise.
Returns the value mapped by name
if it exists and is an int or
can be coerced to an int, or 0 otherwise.
Returns the value mapped by name
if it exists and is a JSONArray
, or null otherwise.
Returns the value mapped by name
if it exists and is a JSONObject
, or null otherwise.
Returns the value mapped by name
if it exists and is a long or
can be coerced to a long, or 0 otherwise. Note that JSON represents numbers as doubles,
so this is lossy; use strings to transfer numbers via JSON.
Returns the value mapped by name
if it exists and is a long or
can be coerced to a long, or fallback
otherwise. Note that JSON represents
numbers as doubles, so this is lossy; use strings to transfer
numbers via JSON.
Returns the value mapped by name
if it exists, coercing it if
necessary, or the empty string if no such mapping exists.
Returns the value mapped by name
if it exists, coercing it if
necessary, or fallback
if no such mapping exists.
Maps name
to value
, clobbering any existing name/value
mapping with the same name.
JSONException |
---|
Maps name
to value
, clobbering any existing name/value
mapping with the same name.
JSONException |
---|
Maps 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 , or null . May not be
NaNs or infinities . |
---|
JSONException |
---|
Maps name
to value
, clobbering any existing name/value
mapping with the same name.
JSONException |
---|
Maps name
to value
, clobbering any existing name/value
mapping with the same name.
value | a finite value. May not be NaNs or
infinities . |
---|
JSONException |
---|
Equivalent to put(name, value)
when both parameters are non-null;
does nothing otherwise.
JSONException |
---|
Encodes 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. |
---|
Removes the named mapping if it exists; does nothing otherwise.
name
, or null if there was
no such mapping.
Returns an array with the values corresponding to names
. The
array contains null for names that aren't mapped. This method returns
null if names
is either null or empty.
JSONException |
---|
Encodes this object as a compact JSON string, such as:
{"query":"Pizza","locations":[94043,90210]}
Encodes this object as a human readable JSON string for debugging, such as:
{ "query": "Pizza", "locations": [ 94043, 90210 ] }
indentSpaces | the number of spaces to indent for each level of nesting. |
---|
JSONException |
---|
Wraps the given object if necessary.
If the object is null or , returns NULL
.
If the object is a JSONArray
or JSONObject
, no wrapping is necessary.
If the object is NULL
, no wrapping is necessary.
If the object is an array or Collection
, returns an equivalent JSONArray
.
If the object is a Map
, returns an equivalent JSONObject
.
If the object is a primitive wrapper type or String
, returns the object.
Otherwise if the object is from a java
package, returns the result of toString
.
If wrapping fails, returns null.