public class JSONObject extends 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
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.
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(JSONTokener readFrom)
Creates a new
JSONObject with name/value mappings from the next object in
the tokener. |
JSONObject(Map copyFrom)
Creates a new
JSONObject by copying all name/value mappings from the given
map. |
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 . |
Object |
get(String name)
Returns the value mapped by
name . |
boolean |
getBoolean(String name)
Returns the value mapped by
name if it exists and is a boolean or can be
coerced to a boolean. |
double |
getDouble(String name)
Returns the value mapped by
name if it exists and is a double or can be
coerced to a double. |
int |
getInt(String name)
Returns the value mapped by
name if it exists and is an int or can be
coerced to an int. |
JSONArray |
getJSONArray(String name)
Returns the value mapped by
name if it exists and is a JSONArray . |
JSONObject |
getJSONObject(String name)
Returns the value mapped by
name if it exists and is a JSONObject . |
long |
getLong(String name)
Returns the value mapped by
name if it exists and is a long or can be
coerced to a long. |
String |
getString(String name)
Returns the value mapped by
name if it exists, coercing it if necessary. |
boolean |
has(String name)
Returns true if this object has a mapping for
name . |
boolean |
isNull(String name)
Returns true if this object has no mapping for
name or if it has a mapping
whose value is NULL . |
Iterator |
keys()
Returns an iterator of the
String names in this object. |
int |
length()
Returns the number of name/value mappings in this object.
|
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(String name)
Returns the value mapped by
name , or null if no such mapping exists. |
boolean |
optBoolean(String name)
Returns the value mapped by
name if it exists and is a boolean or can be
coerced to a boolean. |
boolean |
optBoolean(String name,
boolean fallback)
Returns the value mapped by
name if it exists and is a boolean or can be
coerced to a boolean. |
double |
optDouble(String name)
Returns the value mapped by
name if it exists and is a double or can be
coerced to a double. |
double |
optDouble(String name,
double fallback)
Returns the value mapped by
name if it exists and is a double or can be
coerced to a double. |
int |
optInt(String name)
Returns the value mapped by
name if it exists and is an int or can be
coerced to an int. |
int |
optInt(String name,
int fallback)
Returns the value mapped by
name if it exists and is an int or can be
coerced to an int. |
JSONArray |
optJSONArray(String name)
Returns the value mapped by
name if it exists and is a JSONArray . |
JSONObject |
optJSONObject(String name)
Returns the value mapped by
name if it exists and is a JSONObject . |
long |
optLong(String name)
Returns the value mapped by
name if it exists and is a long or can be
coerced to a long. |
long |
optLong(String name,
long fallback)
Returns the value mapped by
name if it exists and is a long or can be
coerced to a long. |
String |
optString(String name)
Returns the value mapped by
name if it exists, coercing it if necessary. |
String |
optString(String name,
String fallback)
Returns the value mapped by
name if it exists, coercing it if necessary. |
JSONObject |
put(String name,
boolean value)
Maps
name to value , clobbering any existing name/value mapping with
the same name. |
JSONObject |
put(String name,
double value)
Maps
name to value , clobbering any existing name/value mapping with
the same name. |
JSONObject |
put(String name,
int value)
Maps
name to value , clobbering any existing name/value mapping with
the same name. |
JSONObject |
put(String name,
long value)
Maps
name to value , clobbering any existing name/value mapping with
the same name. |
JSONObject |
put(String name,
Object value)
Maps
name to value , clobbering any existing name/value mapping with
the same name. |
JSONObject |
putOpt(String name,
Object value)
Equivalent to
put(name, value) when both parameters are non-null; does
nothing otherwise. |
static String |
quote(String data)
Encodes
data as a JSON string. |
Object |
remove(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 . |
String |
toString()
Encodes this object as a compact JSON string, such as:
|
String |
toString(int indentSpaces)
Encodes this object as a human readable JSON string for debugging, such as:
|
static Object |
wrap(Object o)
Wraps the given object if necessary.
|
public static final Object NULL
null
, names with this value:
names()
array
keys()
iterator
true
for has(String)
get(String)
This value violates the general contract of Object.equals(java.lang.Object)
by returning true
when compared to null
. Its toString()
method returns "null".
public JSONObject()
JSONObject
with no name/value mappings.public JSONObject(Map copyFrom)
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.public JSONObject(JSONTokener readFrom) throws JSONException
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
.public JSONObject(String json) throws JSONException
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
.public JSONObject(JSONObject copyFrom, String[] names) throws JSONException
JSONObject
by copying mappings for the listed names from the
given object. Names that aren't present in copyFrom
will be skipped.copyFrom
- the sourcenames
- the property namesJSONException
- if an error occurspublic int length()
public JSONObject put(String name, boolean value) throws JSONException
name
to value
, clobbering any existing name/value mapping with
the same name.name
- the name of the propertyvalue
- the value of the propertyJSONException
- if an error occurspublic JSONObject put(String name, double value) throws JSONException
name
to value
, clobbering any existing name/value mapping with
the same name.name
- the name of the propertyvalue
- a finite value. May not be NaNs
or
infinities
.JSONException
- if an error occurspublic JSONObject put(String name, int value) throws JSONException
name
to value
, clobbering any existing name/value mapping with
the same name.name
- the name of the propertyvalue
- the value of the propertyJSONException
- if an error occurspublic JSONObject put(String name, long value) throws JSONException
name
to value
, clobbering any existing name/value mapping with
the same name.name
- the name of the propertyvalue
- the value of the propertyJSONException
- if an error occurspublic JSONObject put(String name, 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.name
- the name of the propertyvalue
- a JSONObject
, JSONArray
, String, Boolean, Integer,
Long, Double, NULL
, or null
. May not be NaNs
or infinities
.JSONException
- if an error occurspublic JSONObject putOpt(String name, Object value) throws JSONException
put(name, value)
when both parameters are non-null; does
nothing otherwise.name
- the name of the propertyvalue
- the value of the propertyJSONException
- if an error occurspublic JSONObject accumulate(String name, 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.name
- the name of the propertyvalue
- a JSONObject
, JSONArray
, String, Boolean, Integer,
Long, Double, NULL
or null. May not be NaNs
or
infinities
.JSONException
- if an error occurspublic Object remove(String name)
name
- the name of the propertyname
, or null if there was no such
mapping.public boolean isNull(String name)
name
or if it has a mapping
whose value is NULL
.name
- the name of the propertyname
public boolean has(String name)
name
. The mapping may be
NULL
.name
- the name of the propertyname
public Object get(String name) throws JSONException
name
.name
- the name of the propertyJSONException
- if no such mapping exists.public Object opt(String name)
name
, or null if no such mapping exists.name
- the name of the propertynull
public boolean getBoolean(String name) throws JSONException
name
if it exists and is a boolean or can be
coerced to a boolean.name
- the name of the propertyJSONException
- if the mapping doesn't exist or cannot be coerced to a
boolean.public boolean optBoolean(String name)
name
if it exists and is a boolean or can be
coerced to a boolean. Returns false otherwise.name
- the name of the propertynull
public boolean optBoolean(String name, boolean fallback)
name
if it exists and is a boolean or can be
coerced to a boolean. Returns fallback
otherwise.name
- the name of the propertyfallback
- a fallback valuefallback
public double getDouble(String name) throws JSONException
name
if it exists and is a double or can be
coerced to a double.name
- the name of the propertyJSONException
- if the mapping doesn't exist or cannot be coerced to a
double.public double optDouble(String name)
name
if it exists and is a double or can be
coerced to a double. Returns NaN
otherwise.name
- the name of the propertyNaN
public double optDouble(String name, double fallback)
name
if it exists and is a double or can be
coerced to a double. Returns fallback
otherwise.name
- the name of the propertyfallback
- a fallback valuefallback
public int getInt(String name) throws JSONException
name
if it exists and is an int or can be
coerced to an int.name
- the name of the propertyJSONException
- if the mapping doesn't exist or cannot be coerced to an int.public int optInt(String name)
name
if it exists and is an int or can be
coerced to an int. Returns 0 otherwise.name
- the name of the property0
public int optInt(String name, int fallback)
name
if it exists and is an int or can be
coerced to an int. Returns fallback
otherwise.name
- the name of the propertyfallback
- a fallback valuefallback
public long getLong(String name) throws JSONException
name
if it exists and is a long or can be
coerced to a long. Note that JSON represents numbers as doubles, so this is
lossy; use strings to transfer numbers via JSON.name
- the name of the propertyJSONException
- if the mapping doesn't exist or cannot be coerced to a long.public long optLong(String name)
name
if it exists and is a long or can be
coerced to a long. Returns 0 otherwise. Note that JSON represents numbers as
doubles, so this is lossy; use strings to transfer numbers via
JSON.name
- the name of the property0L
public long optLong(String name, long fallback)
name
if it exists and is a long or can be
coerced to a long. Returns fallback
otherwise. Note that JSON represents
numbers as doubles, so this is lossy; use strings to transfer
numbers via JSON.name
- the name of the propertyfallback
- a fallback valuefallback
public String getString(String name) throws JSONException
name
if it exists, coercing it if necessary.name
- the name of the propertyJSONException
- if no such mapping exists.public String optString(String name)
name
if it exists, coercing it if necessary.
Returns the empty string if no such mapping exists.name
- the name of the propertypublic String optString(String name, String fallback)
name
if it exists, coercing it if necessary.
Returns fallback
if no such mapping exists.name
- the name of the propertyfallback
- a fallback valuefallback
public JSONArray getJSONArray(String name) throws JSONException
name
if it exists and is a JSONArray
.name
- the name of the propertyJSONException
- if the mapping doesn't exist or is not a JSONArray
.public JSONArray optJSONArray(String name)
name
if it exists and is a JSONArray
. Returns null otherwise.name
- the name of the propertynull
public JSONObject getJSONObject(String name) throws JSONException
name
if it exists and is a JSONObject
.name
- the name of the propertyJSONException
- if the mapping doesn't exist or is not a JSONObject
.public JSONObject optJSONObject(String name)
name
if it exists and is a JSONObject
. Returns null otherwise.name
- the name of the propertynull
public JSONArray toJSONArray(JSONArray names)
names
. The array contains
null for names that aren't mapped. This method returns null if names
is
either null or empty.names
- the names of the propertiespublic Iterator 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 JSONArray names()
public String toString()
{"query":"Pizza","locations":[94043,90210]}
public String toString(int indentSpaces) throws JSONException
{ "query": "Pizza", "locations": [ 94043, 90210 ] }
indentSpaces
- the number of spaces to indent for each level of nesting.JSONException
- if an error occurspublic static String numberToString(Number number) throws JSONException
number
- a finite value. May not be NaNs
or
infinities
.JSONException
- if an error occurspublic 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 static Object wrap(Object o)
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.
o
- the object to wrap