JSONObject
public class JSONObject
extends Object
一组可修改的名称/值映射。 名称是唯一的非空字符串。 值可以是任意搭配JSONObjects
, JSONArrays
,字符串,布尔,整型,长,双打或NULL
。 值可能不null
, NaNs
, infinities
,或者这里没有列出任何类型的。
请求时,此类可将值强制为另一种类型。
- 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".
这个类可以查找强制值和可选值:
- 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.
警告:此类以两种不兼容的方式表示空值:标准Java null
引用和标记值NULL
。 特别是,调用put(name, null)
会从对象中删除指定的条目,但put(name, JSONObject.NULL)
存储值为JSONObject.NULL
的条目。
这个类的实例不是线程安全的。 虽然这个类是非终结性的,但它不是为继承而设计的,也不应该被继承。 特别是,没有指定可覆盖方法的自我使用。 有关更多信息,请参见有效Java项目17“设计和文档或继承或禁止它”。
Summary
Fields |
public static final Object |
NULL 标记值用于明确定义没有值的名称。 |
Public methods |
JSONObject |
accumulate(String name, Object value) 将 value 附加到已映射到 name 的阵列。 |
Object |
get(String name) 返回由 name 映射的值,或者如果不存在这样的映射则抛出。 |
boolean |
getBoolean(String name) 返回 name 映射的值(如果它存在并且是布尔值,或者可以强制为布尔值),否则返回。 |
double |
getDouble(String name) 如果它存在且返回值为 name ,则为double,或者可以强制为double,否则返回。 |
int |
getInt(String name) 如果它存在且返回值为 name 则该值为int或可强制为int,否则返回。 |
JSONArray |
getJSONArray(String name) 如果它存在并且是 JSONArray ,则返回由 name 映射的值,否则返回。 |
JSONObject |
getJSONObject(String name) 返回 name 映射的值(如果它存在且为 JSONObject ,否则返回。 |
long |
getLong(String name) 返回 name 映射的值,如果它存在并且很长或者可以被强制为一个long或否则抛出。 |
String |
getString(String name) 如果存在,则返回由 name 映射的值,如有必要则强制该值,如果不存在此类映射,则返回该值。 |
boolean |
has(String name) 如果此对象具有 name 的映射,则返回true。 |
boolean |
isNull(String name) 如果这个对象有没有映射,则返回true name ,或者如果它有一个映射,其值是 NULL 。 |
Iterator<String> |
keys() 返回此对象中 String 名称的迭代器。 |
int |
length() 返回此对象中的名称/值映射的数量。 |
JSONArray |
names() 返回包含此对象中字符串名称的数组。 |
static String |
numberToString(Number number) 将数字编码为JSON字符串。 |
Object |
opt(String name) 返回由 name 映射的值,如果不存在此类映射,则返回null。 |
boolean |
optBoolean(String name, boolean fallback) 返回 name 映射的值(如果它存在并且是布尔值或可以强制为布尔值),否则 fallback 。 |
boolean |
optBoolean(String name) 如果存在并且是布尔值,则返回由 name 映射的值,或者可以强制为布尔值,否则返回false。 |
double |
optDouble(String name, double fallback) 返回由 name 映射的值(如果它存在并且是双 name 值或可以强制为双 fallback 否则 fallback 。 |
double |
optDouble(String name) 返回 name 映射的值(如果它存在并且是双 name 值或可以强制为双 NaN 否则 NaN 。 |
int |
optInt(String name, int fallback) 返回 name 映射的值(如果它存在并且是一个int或可以强制为int),否则 fallback 。 |
int |
optInt(String name) 如果它存在且返回值为 name 则该值为int或可强制为int,否则返回0。 |
JSONArray |
optJSONArray(String name) 返回 name 映射的值(如果它存在且为 JSONArray ,否则返回null。 |
JSONObject |
optJSONObject(String name) 返回 name 映射的值(如果它存在且为 JSONObject ,否则返回null。 |
long |
optLong(String name) 如果它存在且返回值为 name 则返回值为long或可强制为long,否则返回0。 |
long |
optLong(String name, long fallback) 返回 name 映射的值,如果它存在并且很长,或者可以强制为长 fallback 否则 fallback 。 |
String |
optString(String name, String fallback) 如果存在,则返回由 name 映射的值,如有必要则强制 name 该值,如果不存在此类映射,则 fallback 。 |
String |
optString(String name) 如果存在,则返回由 name 映射的值,如有必要则强制 name 该值,如果不存在此类映射,则返回空字符串。 |
JSONObject |
put(String name, double value) 映射 name 到 value ,用相同的名称对任何现有的名称/值映射进行破坏。 |
JSONObject |
put(String name, boolean value) 地图 name 至 value ,以同名的名称对任何现有的名称/值映射进行破坏。 |
JSONObject |
put(String name, int value) 地图 name 至 value ,以相同的名称对任何现有名称/值映射进行破坏。 |
JSONObject |
put(String name, long value) 地图 name 至 value ,以同名的名称对所有现有名称/值映射进行破坏。 |
JSONObject |
put(String name, Object value) 映射 name 到 value ,用相同的名称对任何现有的名称/值映射进行破坏。 |
JSONObject |
putOpt(String name, Object value) 等于put(name, value) 当两个参数都非空时; 否则什么也不做。 |
static String |
quote(String data) 将 data 编码为JSON字符串。 |
Object |
remove(String name) 删除指定的映射(如果存在); 否则什么也不做。 |
JSONArray |
toJSONArray(JSONArray names) 返回值为 names 的数组。 |
String |
toString() 将此对象编码为紧凑的JSON字符串,例如: {"query":"Pizza","locations":[94043,90210]} |
String |
toString(int indentSpaces) 将此对象编码为用于调试的可读JSON字符串,例如:
{
"query": "Pizza",
"locations": [
94043,
90210
]
} |
static Object |
wrap(Object o) 必要时包裹给定的对象。 |
Fields
Public constructors
JSONObject
JSONObject ()
创建一个没有名称/值映射的 JSONObject
。
JSONObject
JSONObject (Map copyFrom)
通过复制给定映射中的所有名称/值映射来创建新的 JSONObject
。
Parameters |
copyFrom |
Map : a map whose keys are of type String and whose values are of supported types. |
JSONObject
JSONObject (JSONTokener readFrom)
创建一个新 JSONObject
与从tokener的下一个对象的名称/值映射。
Parameters |
readFrom |
JSONTokener : a tokener whose nextValue() method will yield a JSONObject . |
Throws |
JSONException |
if the parse fails or doesn't yield a JSONObject . |
JSONObject
JSONObject (String json)
使用来自JSON字符串的名称/值映射创建新的 JSONObject
。
Parameters |
json |
String : a JSON-encoded string containing an object. |
Throws |
JSONException |
if the parse fails or doesn't yield a JSONObject . |
JSONObject
JSONObject (JSONObject copyFrom,
String[] names)
通过复制给定对象中所列名称的映射来创建新的JSONObject
。 不在copyFrom
中的copyFrom
将被跳过。
Parameters |
copyFrom |
JSONObject
|
names |
String
|
Public methods
accumulate
JSONObject accumulate (String name,
Object value)
将value
附加到已映射到name
的阵列。 如果此对象没有映射name
, name
插入一个新的映射。 如果映射存在但其值不是数组,则现有值和新值name
顺序插入到新映射到name
数组中。 总的来说,这允许将值一次添加到映射中。
请注意, append(String, Object)
提供了更好的语义。 特别是, name
的映射将始终为JSONArray
。 使用accumulate
将导致JSONArray
或其类型为value
类型的映射,具体取决于对其的调用次数。
getBoolean
boolean getBoolean (String name)
如果它存在且返回值为 name
则该值为布尔值或可强制为布尔值,否则返回。
Throws |
JSONException |
if the mapping doesn't exist or cannot be coerced to a boolean. |
getDouble
double getDouble (String name)
如果它存在且返回值为 name
,则为double,或者可以强制为double,否则返回。
Throws |
JSONException |
if the mapping doesn't exist or cannot be coerced to a double. |
getInt
int getInt (String name)
如果它存在且返回值为 name
则该值为int或可强制为int,否则返回。
Throws |
JSONException |
if the mapping doesn't exist or cannot be coerced to an int. |
getJSONArray
JSONArray getJSONArray (String name)
返回 name
映射的值(如果它存在且为 JSONArray
,否则返回。
Throws |
JSONException |
if the mapping doesn't exist or is not a JSONArray . |
getJSONObject
JSONObject getJSONObject (String name)
如果它存在并且是 JSONObject
,则返回由 name
映射的值,否则返回。
Throws |
JSONException |
if the mapping doesn't exist or is not a JSONObject . |
getLong
long getLong (String name)
如果它存在且返回由name
映射的值, name
该值长或可被强制为long,否则返回。 请注意,JSON表示数字为双打,所以这是lossy ; 使用字符串通过JSON传输数字。
Throws |
JSONException |
if the mapping doesn't exist or cannot be coerced to a long. |
getString
String getString (String name)
如果存在,则返回由 name
映射的值,如有必要则强制该值,如果不存在此映射,则返回该值。
has
boolean has (String name)
如果此对象具有name
的映射,则返回true。 映射可以是NULL
。
isNull
boolean isNull (String name)
如果这个对象有没有映射,则返回true name
,或者如果它有一个映射,其值是 NULL
。
keys
Iterator<String> keys ()
返回此对象中String
名称的迭代器。 返回的迭代器支持remove
,它将从该对象中删除相应的映射。 如果在迭代器返回后修改该对象,则迭代器的行为是未定义的。 密钥的顺序是未定义的。
length
int length ()
返回此对象中的名称/值映射的数量。
names
JSONArray names ()
返回包含此对象中字符串名称的数组。 如果此对象不包含映射,则此方法返回null。
numberToString
String numberToString (Number number)
将数字编码为JSON字符串。
Parameters |
number |
Number : a finite value. May not be NaNs or infinities . |
opt
Object opt (String name)
返回由 name
映射的值,如果不存在这样的映射,则返回null。
optBoolean
boolean optBoolean (String name,
boolean fallback)
如果它存在并且是布尔值,则返回由 name
映射的值,或者可以强制为布尔值,否则 fallback
。
Parameters |
name |
String
|
fallback |
boolean
|
optBoolean
boolean optBoolean (String name)
如果它存在并且是布尔值,则返回由 name
映射的值,或者可以强制为布尔值,否则返回false。
optDouble
double optDouble (String name,
double fallback)
返回 name
映射的值(如果它存在并且是双 name
值或可以强制为双 fallback
否则 fallback
。
Parameters |
name |
String
|
fallback |
double
|
optDouble
double optDouble (String name)
返回 name
映射的值(如果它存在且为双 name
值或可以强制为双 NaN
否则 NaN
。
optInt
int optInt (String name,
int fallback)
返回 name
映射的值(如果它存在并且是一个int或可以强制为int),否则 fallback
。
Parameters |
name |
String
|
fallback |
int
|
optInt
int optInt (String name)
如果它存在且返回值为 name
则该值为int或可强制为int,否则返回0。
optJSONArray
JSONArray optJSONArray (String name)
返回 name
映射的值(如果它存在且为 JSONArray
,否则返回null。
optJSONObject
JSONObject optJSONObject (String name)
返回 name
映射的值(如果它存在且为 JSONObject
,否则返回null。
optLong
long optLong (String name)
返回name
映射的值,如果它存在并且很长或可以强制为长name
,否则返回0。 请注意,JSON表示数字为双打,所以这是lossy ; 使用字符串通过JSON传输数字。
optLong
long optLong (String name,
long fallback)
返回name
映射的值(如果它存在并且很长或可以强制为长fallback
否则fallback
。 请注意,JSON表示数字为双打,所以这是lossy ; 使用字符串通过JSON传输数字。
Parameters |
name |
String
|
fallback |
long
|
optString
String optString (String name,
String fallback)
如果存在,则返回由 name
映射的值,如有必要则强制 name
该值,如果不存在此类映射,则 fallback
。
Parameters |
name |
String
|
fallback |
String
|
optString
String optString (String name)
如果存在,则返回由 name
映射的值,如有必要则强制 name
该值,如果不存在此类映射,则返回空字符串。
put
JSONObject put (String name,
double value)
映射 name
到 value
,用相同的名称对任何现有名称/值映射进行破坏。
Parameters |
name |
String
|
value |
double : a finite value. May not be NaNs or infinities . |
put
JSONObject put (String name,
boolean value)
映射 name
到 value
,用相同的名称对任何现有的名称/值映射进行破坏。
Parameters |
name |
String
|
value |
boolean
|
put
JSONObject put (String name,
int value)
地图 name
至 value
,使用相同名称对所有现有的名称/值映射进行破坏。
Parameters |
name |
String
|
value |
int
|
put
JSONObject put (String name,
long value)
地图 name
至 value
,以同名的名称对所有现有名称/值映射进行破坏。
Parameters |
name |
String
|
value |
long
|
put
JSONObject put (String name,
Object value)
地图name
至value
,使用相同名称对所有现有的名称/值映射进行破坏。 如果该值是null
,对于任何现有映射name
被去除。
putOpt
JSONObject putOpt (String name,
Object value)
相当于put(name, value)
当两个参数都非空时; 否则什么也不做。
Parameters |
name |
String
|
value |
Object
|
quote
String quote (String data)
将data
编码为JSON字符串。 这适用于引号和任何必要的字符转义。
Parameters |
data |
String : the string to encode. Null will be interpreted as an empty string. |
remove
Object remove (String name)
删除指定的映射(如果存在); 否则什么也不做。
Returns |
Object |
the value previously mapped by name , or null if there was no such mapping. |
toJSONArray
JSONArray toJSONArray (JSONArray names)
返回值为names
的数组。 该数组对于未映射的名称包含空值。 如果names
为null或空,则此方法返回null。
Parameters |
names |
JSONArray
|
toString
String toString ()
将此对象编码为紧凑的JSON字符串,例如:
{"query":"Pizza","locations":[94043,90210]}
Returns |
String |
a string representation of the object. |
toString
String toString (int indentSpaces)
将此对象编码为用于调试的可读JSON字符串,例如:
{
"query": "Pizza",
"locations": [
94043,
90210
]
}
Parameters |
indentSpaces |
int : the number of spaces to indent for each level of nesting. |
wrap
Object wrap (Object o)
必要时包裹给定的对象。
如果该对象为空或返回NULL
。 如果对象是JSONArray
或JSONObject
,则不需要换行。 如果对象是NULL
,则不需要包装。 如果对象是数组或Collection
,则返回等效的JSONArray
。 如果对象是Map
,则返回相应的JSONObject
。 如果该对象是基本包装类型或String
,则返回该对象。 否则,如果对象来自java
包,则返回toString
的结果。 如果包装失败,则返回null。