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:
get
Type
()
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.
opt
Type
()
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.