org.json.JSONObject
A JSONObject is an unordered collection of name/value pairs. Its
external form is a string wrapped in curly braces with colons between the
names and values, and commas between the values and names. The internal form
is an object having get
and opt
methods for
accessing the values by name, and put
methods for adding or
replacing values by name. The values can be any of these types:
Boolean
, JSONArray
, JSONObject
,
Number
, String
, or the JSONObject.NULL
object. A JSONObject constructor can be used to convert an external form
JSON text into an internal form whose values can be retrieved with the
get
and opt
methods, or to convert values into a
JSON text using the put
and toString
methods.
A get
method returns a value if one can be found, and throws an
exception if one cannot be found. An opt
method returns a
default value instead of throwing an exception, and so is useful for
obtaining optional values.
The generic get()
and opt()
methods return an
object, which you can cast or query for type. There are also typed
get
and opt
methods that do type checking and type
coersion for you.
The put
methods adds values to an object. For example,
myString = new JSONObject().put("JSON", "Hello, World!").toString();
produces the string
{"JSON": "Hello, World"}
.
The texts produced by the toString
methods strictly conform to
the JSON sysntax rules.
The constructors are more forgiving in the texts they will accept:
- An extra
,
(comma) may appear just
before the closing brace.
- Strings may be quoted with
'
(single
quote).
- Strings do not need to be quoted at all if they do not begin with a quote
or single quote, and if they do not contain leading or trailing spaces,
and if they do not contain any of these characters:
{ } [ ] / \ : , = ; #
and if they do not look like numbers
and if they are not the reserved words true
,
false
, or null
.
- Keys can be followed by
=
or =>
as well as
by :
.
- Values can be followed by
;
(semicolon) as
well as by ,
(comma).
- Numbers may have the
0-
(octal) or
0x-
(hex) prefix.
- Comments written in the slashshlash, slashstar, and hash conventions
will be ignored.
Summary
Constants
|
|
|
Value |
|
Object |
NULL |
It is sometimes more convenient and less ambiguous to have a
NULL object than to use Java's null value. |
|
|
Public Constructors
Public Methods
|
|
|
|
|
JSONObject |
accumulate(String key, Object value) |
|
|
|
|
|
Object |
get(String key) |
|
|
|
|
|
boolean |
getBoolean(String key) |
|
|
|
|
|
double |
getDouble(String key) |
|
|
|
|
|
int |
getInt(String key) |
|
|
|
|
|
JSONArray |
getJSONArray(String key) |
|
|
|
|
|
JSONObject |
getJSONObject(String key) |
|
|
|
|
|
long |
getLong(String key) |
|
|
|
|
|
String |
getString(String key) |
|
|
|
|
|
boolean |
has(String key) |
|
|
|
|
|
boolean |
isNull(String key) |
|
|
|
|
|
Iterator |
keys() |
|
|
|
|
|
int |
length() |
|
|
|
|
|
JSONArray |
names() |
|
|
|
static |
|
String |
numberToString(Number n) |
|
|
|
|
|
Object |
opt(String key) |
|
|
|
|
|
boolean |
optBoolean(String key) |
|
|
|
|
|
boolean |
optBoolean(String key, boolean defaultValue) |
|
|
|
|
|
double |
optDouble(String key) |
|
|
|
|
|
double |
optDouble(String key, double defaultValue) |
|
|
|
|
|
int |
optInt(String key, int defaultValue) |
|
|
|
|
|
int |
optInt(String key) |
|
|
|
|
|
JSONArray |
optJSONArray(String key) |
|
|
|
|
|
JSONObject |
optJSONObject(String key) |
|
|
|
|
|
long |
optLong(String key, long defaultValue) |
|
|
|
|
|
long |
optLong(String key) |
|
|
|
|
|
String |
optString(String key, String defaultValue) |
|
|
|
|
|
String |
optString(String key) |
|
|
|
|
|
JSONObject |
put(String key, boolean value) |
|
|
|
|
|
JSONObject |
put(String key, double value) |
|
|
|
|
|
JSONObject |
put(String key, Object value) |
|
|
|
|
|
JSONObject |
put(String key, int value) |
|
|
|
|
|
JSONObject |
put(String key, long value) |
|
|
|
|
|
JSONObject |
putOpt(String key, Object value) |
|
|
|
static |
|
String |
quote(String string) |
|
|
|
|
|
Object |
remove(String key) |
|
|
|
|
|
JSONArray |
toJSONArray(JSONArray names) |
|
|
|
|
|
String |
toString() |
|
|
|
|
|
String |
toString(int indentFactor) |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
public
static
final
Object
NULL
It is sometimes more convenient and less ambiguous to have a
NULL
object than to use Java's null
value.
JSONObject.NULL.equals(null)
returns true
.
JSONObject.NULL.toString()
returns "null"
.
Public Constructors
public
JSONObject()
Construct an empty JSONObject.
Construct a JSONObject from a subset of another JSONObject.
An array of strings is used to identify the keys that should be copied.
Missing keys are ignored.
Parameters
jo
| A JSONObject. |
sa
| An array of strings. |
Construct a JSONObject from a JSONTokener.
Parameters
x
| A JSONTokener object containing the source string. |
public
JSONObject(Map map)
Construct a JSONObject from a Map.
Parameters
map
| A map object that can be used to initialize the contents of
the JSONObject.
|
public
JSONObject(String string)
Construct a JSONObject from a string.
This is the most commonly used JSONObject constructor.
Parameters
string
| A string beginning
with { (left brace) and ending
with } (right brace). |
Public Methods
Accumulate values under a key. It is similar to the put method except
that if there is already an object stored under the key then a
JSONArray is stored under the key to hold all of the accumulated values.
If there is already a JSONArray, then the new value is appended to it.
In contrast, the put method replaces the previous value.
Parameters
key
| A key string. |
value
| An object to be accumulated under the key. |
Throws
JSONException
| If the value is an invalid number
or if the key is null.
|
Get the value object associated with a key.
Returns
- The object associated with the key.
public
boolean
getBoolean(String key)
Get the boolean value associated with a key.
Throws
JSONException
| if the value is not a Boolean or the String "true" or "false".
|
public
double
getDouble(String key)
Get the double value associated with a key.
Throws
JSONException
| if the key is not found or
if the value is not a Number object and cannot be converted to a number.
|
public
int
getInt(String key)
Get the int value associated with a key. If the number value is too
large for an int, it will be clipped.
Throws
JSONException
| if the key is not found or if the value cannot
be converted to an integer.
|
Get the JSONArray value associated with a key.
Returns
- A JSONArray which is the value.
Throws
JSONException
| if the key is not found or
if the value is not a JSONArray.
|
Get the JSONObject value associated with a key.
Returns
- A JSONObject which is the value.
Throws
JSONException
| if the key is not found or
if the value is not a JSONObject.
|
public
long
getLong(String key)
Get the long value associated with a key. If the number value is too
long for a long, it will be clipped.
Throws
JSONException
| if the key is not found or if the value cannot
be converted to a long.
|
Get the string associated with a key.
Returns
- A string which is the value.
public
boolean
has(String key)
Determine if the JSONObject contains a specific key.
Returns
- true if the key exists in the JSONObject.
public
boolean
isNull(String key)
Determine if the value associated with the key is null or if there is
no value.
Returns
- true if there is no value associated with the key or if
the value is the JSONObject.NULL object.
Get an enumeration of the keys of the JSONObject.
public
int
length()
Get the number of keys stored in the JSONObject.
Returns
- The number of keys in the JSONObject.
Produce a JSONArray containing the names of the elements of this
JSONObject.
Returns
- A JSONArray containing the key strings, or null if the JSONObject
is empty.
public
static
String
numberToString(Number n)
Produce a string from a number.
Get an optional value associated with a key.
Returns
- An object which is the value, or null if there is no value.
public
boolean
optBoolean(String key)
Get an optional boolean associated with a key.
It returns false if there is no such key, or if the value is not
Boolean.TRUE or the String "true".
public
boolean
optBoolean(String key, boolean defaultValue)
Get an optional boolean associated with a key.
It returns the defaultValue if there is no such key, or if it is not
a Boolean or the String "true" or "false" (case insensitive).
Parameters
key
| A key string. |
defaultValue
| The default. |
public
double
optDouble(String key)
Get an optional double associated with a key,
or NaN if there is no such key or if its value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Parameters
key
| A string which is the key. |
Returns
- An object which is the value.
public
double
optDouble(String key, double defaultValue)
Get an optional double associated with a key, or the
defaultValue if there is no such key or if its value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Parameters
key
| A key string. |
defaultValue
| The default. |
Returns
- An object which is the value.
public
int
optInt(String key, int defaultValue)
Get an optional int value associated with a key,
or the default if there is no such key or if the value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Parameters
key
| A key string. |
defaultValue
| The default. |
Returns
- An object which is the value.
public
int
optInt(String key)
Get an optional int value associated with a key,
or zero if there is no such key or if the value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Returns
- An object which is the value.
Get an optional JSONArray associated with a key.
It returns null if there is no such key, or if its value is not a
JSONArray.
Returns
- A JSONArray which is the value.
Get an optional JSONObject associated with a key.
It returns null if there is no such key, or if its value is not a
JSONObject.
Returns
- A JSONObject which is the value.
public
long
optLong(String key, long defaultValue)
Get an optional long value associated with a key,
or the default if there is no such key or if the value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Parameters
key
| A key string. |
defaultValue
| The default. |
Returns
- An object which is the value.
public
long
optLong(String key)
Get an optional long value associated with a key,
or zero if there is no such key or if the value is not a number.
If the value is a string, an attempt will be made to evaluate it as
a number.
Returns
- An object which is the value.
public
String
optString(String key, String defaultValue)
Get an optional string associated with a key.
It returns the defaultValue if there is no such key.
Parameters
key
| A key string. |
defaultValue
| The default. |
Returns
- A string which is the value.
Get an optional string associated with a key.
It returns an empty string if there is no such key. If the value is not
a string and is not null, then it is coverted to a string.
Returns
- A string which is the value.
Put a key/boolean pair in the JSONObject.
Parameters
key
| A key string. |
value
| A boolean which is the value. |
Put a key/double pair in the JSONObject.
Parameters
key
| A key string. |
value
| A double which is the value. |
Put a key/value pair in the JSONObject. If the value is null,
then the key will be removed from the JSONObject if it is present.
Parameters
key
| A key string. |
value
| An object which is the value. It should be of one of these
types: Boolean, Double, Integer, JSONArray, JSONObject, Long, String,
or the JSONObject.NULL object. |
Throws
JSONException
| If the value is non-finite number
or if the key is null.
|
Put a key/int pair in the JSONObject.
Parameters
key
| A key string. |
value
| An int which is the value. |
Put a key/long pair in the JSONObject.
Parameters
key
| A key string. |
value
| A long which is the value. |
Put a key/value pair in the JSONObject, but only if the
key and the value are both non-null.
Parameters
key
| A key string. |
value
| An object which is the value. It should be of one of these
types: Boolean, Double, Integer, JSONArray, JSONObject, Long, String,
or the JSONObject.NULL object. |
public
static
String
quote(String string)
Produce a string in double quotes with backslash sequences in all the
right places. A backslash will be inserted within </, allowing JSON
text to be delivered in HTML. In JSON text, a string cannot contain a
control character or an unescaped quote or backslash.
Returns
- A String correctly formatted for insertion in a JSON text.
Remove a name and its value, if present.
Parameters
key
| The name to be removed. |
Returns
- The value that was associated with the name,
or null if there was no value.
Produce a JSONArray containing the values of the members of this
JSONObject.
Parameters
names
| A JSONArray containing a list of key strings. This
determines the sequence of the values in the result. |
public
String
toString()
Make an JSON text of this JSONObject. For compactness, no whitespace
is added. If this would not result in a syntactically correct JSON text,
then null will be returned instead.
Warning: This method assumes that the data structure is acyclical.
Returns
- a printable, displayable, portable, transmittable
representation of the object, beginning
with
{
(left brace) and ending
with }
(right brace).
public
String
toString(int indentFactor)
Make a prettyprinted JSON text of this JSONObject.
Warning: This method assumes that the data structure is acyclical.
Parameters
indentFactor
| The number of spaces to add to each level of
indentation. |
Returns
- a printable, displayable, portable, transmittable
representation of the object, beginning
with
{
(left brace) and ending
with }
(right brace).