JSONObject

public class JSONObject extends Object

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.

  • When the requested type is a boolean, strings will be coerced using a case-insensitive comparison to "true" and "false".
  • When the requested type is a double, other Number types will be coerced using doubleValue. Strings that can be coerced using valueOf(String) will be.
  • When the requested type is an int, other Number types will be coerced using intValue. Strings that can be coerced using valueOf(String) will be, and then cast to int.
  • When the requested type is a long, other 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.
  • When the requested type is a String, other non-null values will be coerced using 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:

  • Use 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.
  • Use 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.

Field Summary

public static final Object NULL A sentinel value used to explicitly define a name with no value.

Public Constructor Summary

JSONObject()
Creates a JSONObject with no name/value mappings.
JSONObject(Map copyFrom)
Creates a new JSONObject by copying all name/value mappings from the given map.
JSONObject(JSONTokener readFrom)
Creates a new JSONObject with name/value mappings from the next object in the tokener.
JSONObject(String json)
Creates a new JSONObject with name/value mappings from the JSON string.
JSONObject(JSONObject copyFrom, String[] names)
Creates a new JSONObject by copying mappings for the listed names from the given object.

Public Method Summary

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, 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.
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.
JSONArray
getJSONArray(String name)
Returns the value mapped by name if it exists and is a JSONArray, or throws otherwise.
JSONObject
getJSONObject(String name)
Returns the value mapped by name if it exists and is a JSONObject, or throws otherwise.
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.
String
getString(String name)
Returns the value mapped by name if it exists, coercing it if necessary, or throws if no such mapping exists.
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<String>
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, boolean fallback)
Returns the value mapped by name if it exists and is a boolean or can be coerced to a boolean, or fallback otherwise.
boolean
optBoolean(String name)
Returns the value mapped by name if it exists and is a boolean or can be coerced to a boolean, or false otherwise.
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, or fallback otherwise.
double
optDouble(String name)
Returns the value mapped by name if it exists and is a double or can be coerced to a double, or NaN otherwise.
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, or fallback otherwise.
int
optInt(String name)
Returns the value mapped by name if it exists and is an int or can be coerced to an int, or 0 otherwise.
JSONArray
optJSONArray(String name)
Returns the value mapped by name if it exists and is a JSONArray, or null otherwise.
JSONObject
optJSONObject(String name)
Returns the value mapped by name if it exists and is a JSONObject, or null otherwise.
long
optLong(String name)
Returns the value mapped by name if it exists and is a long or can be coerced to a long, or 0 otherwise.
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, or fallback otherwise.
String
optString(String name, String fallback)
Returns the value mapped by name if it exists, coercing it if necessary, or fallback if no such mapping exists.
String
optString(String name)
Returns the value mapped by name if it exists, coercing it if necessary, or the empty string if no such mapping exists.
JSONObject
put(String name, double value)
Maps name to value, clobbering any existing name/value mapping with the same name.