Package processing.data
Class JSONObject
java.lang.Object
processing.data.JSONObject
A JSONObject stores JSON data with multiple name/value pairs. Values
can be numeric, Strings, booleans, other JSONObjects or
JSONArrays, or null. JSONObject and JSONArray objects
are quite similar and share most of the same methods; the primary difference
is that the latter stores an array of JSON objects, while the former
represents a single JSON object.
JSON can be generated from scratch, dynamically, or using data from an existing file. JSON can also be output and saved to disk, as in the example above.
JSON can be generated from scratch, dynamically, or using data from an existing file. JSON can also be output and saved to disk, as in the example above.
Advanced
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 havingget
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
coercion for you. The opt methods differ from the get methods in that they do
not throw. Instead, they return a specified value, such as null.
The put
methods add or replace values in 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 syntax 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 wordstrue
,false
, ornull
. - Keys can be followed by
=
or=>
as well as by:
. - Values can be followed by
;
(semicolon) as well as by,
(comma).
-
Field Summary
-
Constructor Summary
ConstructorDescriptionConstruct an empty JSONObject.JSONObject
(Reader reader) JSONObject
(FloatDict dict) JSONObject
(IntDict dict) JSONObject
(StringDict dict) -
Method Summary
Modifier and TypeMethodDescriptionformat
(int indentFactor) Make a prettyprinted JSON text of this JSONObject.Get the value object associated with a key.boolean
getBoolean
(String key) Gets the boolean value associated with the specified key.boolean
getBoolean
(String key, boolean defaultValue) Get an optional boolean associated with a key.double
Get the double value associated with a key.double
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.getDoubleList
(String key) float
Gets the float value associated with the specified keyfloat
getFloatList
(String key) int
Gets the int value associated with the specified key.int
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.getIntList
(String key) getJSONArray
(String key) Retrieves the JSONArray with the associated key.getJSONObject
(String key) Given a key value, retrieves the associated JSONObject.long
Get the long value associated with a key.long
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.getLongList
(String key) Gets the String value associated with the specified key.Get an optional string associated with a key.getStringList
(String key) boolean
Determine if the JSONObject contains a specific key.boolean
Determines if the value associated with the key is null, that is has no defined value (false) or if it has a value (true).Get an enumeration of the keys of the JSONObject.keys()
Get a set of keys of the JSONObject.static JSONObject
Construct a JSONObject from a source JSON text string.Put a key/value pair in the JSONObject.static String
Produce a string in double quotes with backslash sequences in all the right places.static Writer
Remove a name and its value, if present.boolean
setBoolean
(String key, boolean value) Inserts a new key/boolean pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.Put a key/double pair in the JSONObject.Inserts a new key/float pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.Inserts a new key/int pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.setJSONArray
(String key, JSONArray value) Sets the value of the JSONArray with the associated key.setJSONObject
(String key, JSONObject value) Sets the value of the JSONObject with the associated key.Put a key/long pair in the JSONObject.Inserts a new key/String pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.int
size()
Get the number of keys stored in the JSONObject.toString()
Return the JSON data formatted with two spaces for indents.boolean
write
(PrintWriter output) boolean
write
(PrintWriter output, String options)
-
Field Details
-
NULL
It is sometimes more convenient and less ambiguous to have aNULL
object than to use Java'snull
value.JSONObject.NULL.equals(null)
returnstrue
.JSONObject.NULL.toString()
returns"null"
.
-
-
Constructor Details
-
JSONObject
public JSONObject()Construct an empty JSONObject. -
JSONObject
-
JSONObject
-
JSONObject
-
JSONObject
-
-
Method Details
-
parse
Construct a JSONObject from a source JSON text string. This is the most commonly used JSONObject constructor.- Parameters:
source
- A string beginning with{
(left brace) and ending with}
(right brace).- Throws:
RuntimeException
- If there is a syntax error in the source string or a duplicated key.
-
get
Get the value object associated with a key.- Parameters:
key
- A key string.- Returns:
- The object associated with the key.
- Throws:
RuntimeException
- if the key is not found.
-
getString
Gets the String value associated with the specified key.- Parameters:
key
- a key string- Returns:
- A string which is the value.
- Throws:
RuntimeException
- if there is no string value for the key.- See Also:
-
getString
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.
-
getInt
Gets the int value associated with the specified key.- Parameters:
key
- A key string.- Returns:
- The integer value.
- Throws:
RuntimeException
- if the key is not found or if the value cannot be converted to an integer.- See Also:
-
getInt
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.
-
getLong
Get the long value associated with a key.- Parameters:
key
- A key string.- Returns:
- The long value.
- Throws:
RuntimeException
- if the key is not found or if the value cannot be converted to a long.
-
getLong
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.
-
getFloat
Gets the float value associated with the specified key- Parameters:
key
- a key string- See Also:
-
getFloat
-
getDouble
Get the double value associated with a key.- Parameters:
key
- A key string.- Returns:
- The numeric value.
- Throws:
RuntimeException
- if the key is not found or if the value is not a Number object and cannot be converted to a number.
-
getDouble
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.
-
getBoolean
Gets the boolean value associated with the specified key.- Parameters:
key
- a key string- Returns:
- The truth.
- Throws:
RuntimeException
- if the value is not a Boolean or the String "true" or "false".- See Also:
-
getBoolean
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.- Returns:
- The truth.
-
getJSONArray
Retrieves the JSONArray with the associated key.- Parameters:
key
- a key string- Returns:
- A JSONArray which is the value, or null if not present
- Throws:
RuntimeException
- if the value is not a JSONArray.- See Also:
-
getIntList
-
getLongList
-
getFloatList
-
getDoubleList
-
getStringList
-
getJSONObject
Given a key value, retrieves the associated JSONObject.- Parameters:
key
- a key string- Returns:
- A JSONObject which is the value or null if not available.
- Throws:
RuntimeException
- if the value is not a JSONObject.- See Also:
-
hasKey
Determine if the JSONObject contains a specific key.- Parameters:
key
- A key string.- Returns:
- true if the key exists in the JSONObject.
-
isNull
Determines if the value associated with the key is null, that is has no defined value (false) or if it has a value (true).- Parameters:
key
- A key string.- Returns:
- true if there is no value associated with the key or if the value is the JSONObject.NULL object.
-
keyIterator
Get an enumeration of the keys of the JSONObject.- Returns:
- An iterator of the keys.
-
keys
Get a set of keys of the JSONObject.- Returns:
- A keySet.
-
size
public int size()Get the number of keys stored in the JSONObject.- Returns:
- The number of keys in the JSONObject.
-
setString
Inserts a new key/String pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.- Parameters:
key
- a key stringvalue
- the value to assign- See Also:
-
setInt
Inserts a new key/int pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.- Parameters:
key
- a key stringvalue
- the value to assign- Returns:
- this.
- Throws:
RuntimeException
- If the key is null.- See Also:
-
setLong
Put a key/long pair in the JSONObject.- Parameters:
key
- A key string.value
- A long which is the value.- Returns:
- this.
- Throws:
RuntimeException
- If the key is null.
-
setFloat
Inserts a new key/float pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.- Parameters:
key
- a key stringvalue
- the value to assign- Throws:
RuntimeException
- If the key is null or if the number is NaN or infinite.- See Also:
-
setDouble
Put a key/double pair in the JSONObject.- Parameters:
key
- A key string.value
- A double which is the value.- Returns:
- this.
- Throws:
RuntimeException
- If the key is null or if the number is NaN or infinite.
-
setBoolean
Inserts a new key/boolean pair into the JSONObject or, if a value with the specified key already exists, assigns a new value.- Parameters:
key
- a key stringvalue
- the value to assign- Returns:
- this.
- Throws:
RuntimeException
- If the key is null.- See Also:
-
setJSONObject
Sets the value of the JSONObject with the associated key.- Parameters:
key
- a key stringvalue
- value to assign- See Also:
-
setJSONArray
Sets the value of the JSONArray with the associated key.- Parameters:
key
- a key stringvalue
- value to assign- See Also:
-
put
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.- Returns:
- this.
- Throws:
RuntimeException
- If the value is non-finite number or if the key is null.
-
quote
Produce a string in double quotes with backslash sequences in all the right places. A backslash will be inserted within </, producing <\/, allowing JSON text to be delivered in HTML. In JSON text, a string cannot contain a control character or an unescaped quote or backslash.- Parameters:
string
- A String- Returns:
- A String correctly formatted for insertion in a JSON text.
-
quote
- Throws:
IOException
-
remove
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.
-
save
-
write
-
write
-
toString
Return the JSON data formatted with two spaces for indents. Chosen to do this since it's the most common case (e.g. with println()). Same as format(2). Use the format() function for more options. -
format
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). - Throws:
RuntimeException
- If the object contains an invalid number.
-