org.json.JSONObject Class Reference

A JSONObject is an unordered collection of name/value pairs. More...

Classes
class	Null
	JSONObject.NULL is equivalent to the value that JavaScript calls null, whilst Java's null is equivalent to the value that JavaScript calls undefined.

Public Member Functions
	JSONObject ()
	Construct an empty JSONObject.
	JSONObject (JSONObject jo, String[] sa)
	Construct a JSONObject from a subset of another JSONObject.
	JSONObject (JSONTokener x) throws ParseException
	Construct a JSONObject from a JSONTokener.
	JSONObject (Map map)
	Construct a JSONObject from a Map.
	JSONObject (String string) throws ParseException
	Construct a JSONObject from a string.
JSONObject	accumulate (String key, Object value) throws NullPointerException
	Accumulate values under a key.
Object	get (String key) throws NoSuchElementException
	Get the value object associated with a key.
boolean	getBoolean (String key) throws ClassCastException, NoSuchElementException
	Get the boolean value associated with a key.
double	getDouble (String key) throws NoSuchElementException, NumberFormatException
	Get the double value associated with a key.
int	getInt (String key) throws NoSuchElementException, NumberFormatException
	Get the int value associated with a key.
JSONArray	getJSONArray (String key) throws NoSuchElementException
	Get the JSONArray value associated with a key.
JSONObject	getJSONObject (String key) throws NoSuchElementException
	Get the JSONObject value associated with a key.
String	getString (String key) throws NoSuchElementException
	Get the string associated with a key.
boolean	has (String key)
	Determine if the JSONObject contains a specific key.
boolean	isNull (String key)
	Determine if the value associated with the key is null or if there is no value.
Iterator	keys ()
	Get an enumeration of the keys of the JSONObject.
int	length ()
	Get the number of keys stored in the JSONObject.
JSONArray	names ()
	Produce a JSONArray containing the names of the elements of this JSONObject.
Object	opt (String key) throws NullPointerException
	Get an optional value associated with a key.
boolean	optBoolean (String key)
	Get an optional boolean associated with a key.
boolean	optBoolean (String key, boolean defaultValue)
	Get an optional boolean associated with a key.
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.
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.
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.
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.
JSONArray	optJSONArray (String key)
	Get an optional JSONArray associated with a key.
JSONObject	optJSONObject (String key)
	Get an optional JSONObject associated with a key.
String	optString (String key)
	Get an optional string associated with a key.
String	optString (String key, String defaultValue)
	Get an optional string associated with a key.
JSONObject	put (String key, boolean value)
	Put a key/boolean pair in the JSONObject.
JSONObject	put (String key, double value)
	Put a key/double pair in the JSONObject.
JSONObject	put (String key, int value)
	Put a key/int pair in the JSONObject.
JSONObject	put (String key, Object value) throws NullPointerException
	Put a key/value pair in the JSONObject.
JSONObject	putOpt (String key, Object value) throws NullPointerException
	Put a key/value pair in the JSONObject, but only if the value is non-null.
Object	remove (String key)
	Remove a name and its value, if present.
JSONArray	toJSONArray (JSONArray names)
	Produce a JSONArray containing the values of the members of this JSONObject.
String	toString ()
	Make an JSON external form string of this JSONObject.
String	toString (int indentFactor)
	Make a prettyprinted JSON external form string of this JSONObject.

Static Public Member Functions
static String	numberToString (Number n) throws ArithmeticException
	Produce a string from a number.
static String	quote (String string)
	Produce a string in double quotes with backslash sequences in all the right places.

Static Public Attributes
static final Object	NULL = new Null()
	It is sometimes more convenient and less ambiguous to have a NULL object than to use Java's null value.

Detailed Description

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.

The constructor can convert an external form string into an internal form Java object. The toString() method creates an external form string.

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 texts produced by the toString() methods are very strict. 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 ; as well as by ,
• Numbers may have the 0- (octal) or 0x- (hex) prefix.
• Line comments can begin with #

Author

JSON.org

Version

1

Constructor & Destructor Documentation

org.json.JSONObject.JSONObject

(

)

Construct an empty JSONObject.

Referenced by org.json.JSONObject.optJSONObject().

org.json.JSONObject.JSONObject	(	JSONObject	jo,
		String[]	sa
	)

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.

References org.json.JSONObject.opt(), and org.json.JSONObject.putOpt().

org.json.JSONObject.JSONObject

(

JSONTokener

x

)

throws ParseException

Construct a JSONObject from a JSONTokener.

Parameters

x	A JSONTokener object containing the source string.

Exceptions

ParseException

if there is a syntax error in the source string.

org.json.JSONObject.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.

org.json.JSONObject.JSONObject

(

String

string

)

throws ParseException

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).

Exceptions

ParseException

The string must be properly formatted.

Member Function Documentation

JSONObject org.json.JSONObject.accumulate	(	String	key,
		Object	value
	)		throws NullPointerException

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.

Returns

this.

Exceptions

NullPointerException

if the key is null

References org.json.JSONObject.opt(), org.json.JSONArray.put(), and org.json.JSONObject.put().

Referenced by sfi.director.application.FrontendHTTPServer.edit_data(), sfi.director.application.FrontendHTTPServer.getEditorErrors(), and sfi.director.application.FrontendHTTPServer.session_enumDomains().

Object org.json.JSONObject.get

(

String

key

)

throws NoSuchElementException

Get the value object associated with a key.

Parameters

key	A key string.

Returns

The object associated with the key.

Exceptions

NoSuchElementException

if the key is not found.

References org.json.JSONObject.opt(), and org.json.JSONObject.quote().

Referenced by sfi.director.repository.DBObject.DBObject(), and org.json.XML.toString().

boolean org.json.JSONObject.getBoolean

(

String

key

)

throws ClassCastException, NoSuchElementException

Get the boolean value associated with a key.

Parameters

key	A key string.

Returns

The truth.

Exceptions

NoSuchElementException	if the key is not found.
ClassCastException	if the value is not a Boolean or the String "true" or "false".

References org.json.JSONObject.quote().

Referenced by org.json.Test.main().

double org.json.JSONObject.getDouble

(

String

key

)

throws NoSuchElementException, NumberFormatException

Get the double value associated with a key.

Parameters

key	A key string.

Returns

The numeric value.

Exceptions

NumberFormatException	if the value cannot be converted to a number.
NoSuchElementException	if the key is not found or if the value is a Number object.

References org.json.JSONObject.quote().

Referenced by org.json.JSONObject.getInt(), and org.json.Test.main().

int org.json.JSONObject.getInt

(

String

key

)

throws NoSuchElementException, NumberFormatException

Get the int value associated with a key.

Parameters

key	A key string.

Returns

The integer value.

Exceptions

NoSuchElementException	if the key is not found
NumberFormatException	if the value cannot be converted to a number.

References org.json.JSONObject.getDouble().

Referenced by org.json.Test.main().

JSONArray org.json.JSONObject.getJSONArray

(

String

key

)

throws NoSuchElementException

Get the JSONArray value associated with a key.

Parameters

key	A key string.

Returns

A JSONArray which is the value.

Exceptions

NoSuchElementException

if the key is not found or if the value is not a JSONArray.

References org.json.JSONObject.quote().

Referenced by org.json.Test.main().

JSONObject org.json.JSONObject.getJSONObject

(

String

key

)

throws NoSuchElementException

Get the JSONObject value associated with a key.

Parameters

key	A key string.

Returns

A JSONObject which is the value.

Exceptions

NoSuchElementException

if the key is not found or if the value is not a JSONObject.

References org.json.JSONObject.quote().

String org.json.JSONObject.getString

(

String

key

)

throws NoSuchElementException

Get the string associated with a key.

Parameters

key	A key string.

Returns

A string which is the value.

Exceptions

NoSuchElementException

if the key is not found.

References org.json.JSONObject.toString().

Referenced by sfi.director.application.FrontendHTTPServer.file_upload(), sfi.director.application.FrontendHTTPServer.handleRpc(), org.json.Test.main(), org.json.CookieList.toString(), and org.json.Cookie.toString().

boolean org.json.JSONObject.has

(

String

key

)

Determine if the JSONObject contains a specific key.

Parameters

key	A key string.

Returns

true if the key exists in the JSONObject.

Referenced by org.json.Test.main(), and org.json.Cookie.toString().

boolean org.json.JSONObject.isNull

(

String

key

)

Determine if the value associated with the key is null or if there is no value.

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.

References org.json.JSONObject.NULL, and org.json.JSONObject.opt().

Referenced by org.json.Test.main(), and org.json.CookieList.toString().

Iterator org.json.JSONObject.keys

(

)

Get an enumeration of the keys of the JSONObject.

Returns

An iterator of the keys.

Referenced by sfi.director.repository.DBObject.DBObject(), sfi.director.application.FrontendHTTPServer.file_upload(), sfi.director.application.FrontendHTTPServer.handleRpc(), org.json.JSONObject.names(), org.json.CookieList.toString(), org.json.XML.toString(), and org.json.JSONObject.toString().

int org.json.JSONObject.length

(

)

Get the number of keys stored in the JSONObject.

Returns

The number of keys in the JSONObject.

Referenced by org.json.JSONObject.quote().

JSONArray org.json.JSONObject.names

(

)

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.

References org.json.JSONObject.keys(), org.json.JSONArray.length(), and org.json.JSONArray.put().

Referenced by org.json.CDL.toString().

static String org.json.JSONObject.numberToString ( Number  n ) throws ArithmeticException

static

Produce a string from a number.

Parameters

n

A Number

Returns

A String.

Exceptions

ArithmeticException

JSON can only serialize finite numbers.

Object org.json.JSONObject.opt

(

String

key

)

throws NullPointerException

Get an optional value associated with a key.

Parameters

key	A key string.

Returns

An object which is the value, or null if there is no value.

Exceptions

NullPointerException

The key must not be null.

Referenced by org.json.JSONObject.accumulate(), org.json.JSONObject.get(), org.json.JSONObject.isNull(), org.json.JSONObject.JSONObject(), org.json.JSONObject.optBoolean(), org.json.JSONObject.optDouble(), org.json.JSONObject.optInt(), org.json.JSONObject.optJSONArray(), org.json.JSONObject.optJSONObject(), org.json.JSONObject.optString(), and org.json.JSONObject.toJSONArray().

boolean org.json.JSONObject.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".

Parameters

key	A key string.

Returns

The truth.

Referenced by org.json.Test.main(), and org.json.Cookie.toString().

boolean org.json.JSONObject.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.

Returns

The truth.

References org.json.JSONObject.opt().

double org.json.JSONObject.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.

double org.json.JSONObject.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.

References org.json.JSONObject.opt().

int org.json.JSONObject.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.

Parameters

key	A key string.

Returns

An object which is the value.

Referenced by org.json.Test.main().

int org.json.JSONObject.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.

References org.json.JSONObject.opt().

JSONArray org.json.JSONObject.optJSONArray

(

String

key

)

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.

Parameters

key	A key string.

Returns

A JSONArray which is the value.

References org.json.JSONObject.opt().

Referenced by sfi.director.application.FrontendHTTPServer.handleRpc(), and sfi.director.application.FrontendHTTPServer.sessionProxy().

JSONObject org.json.JSONObject.optJSONObject

(

String

key

)

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.

Parameters

key	A key string.

Returns

A JSONObject which is the value.

References org.json.JSONObject.JSONObject(), and org.json.JSONObject.opt().

Referenced by sfi.director.application.FrontendHTTPServer.db_request(), sfi.director.application.FrontendHTTPServer.edit_request(), sfi.director.application.FrontendHTTPServer.file_retrieve(), sfi.director.application.FrontendHTTPServer.file_upload(), sfi.director.application.FrontendHTTPServer.handleRpc(), and sfi.director.application.FrontendHTTPServer.util_request().

String org.json.JSONObject.optString

(

String

key

)

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.

Parameters

key	A key string.

Returns

A string which is the value.

Referenced by sfi.director.repository.DBObject.DBObject(), sfi.director.application.FrontendHTTPServer.file_retrieve(), sfi.director.application.FrontendHTTPServer.file_upload(), sfi.director.application.FrontendHTTPServer.handleRpc(), and sfi.director.application.FrontendHTTPServer.sessionProxy().

String org.json.JSONObject.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.

References org.json.JSONObject.opt().

JSONObject org.json.JSONObject.put	(	String	key,
		boolean	value
	)

Put a key/boolean pair in the JSONObject.

Parameters

key	A key string.
value	A boolean which is the value.

Returns

this.

Referenced by org.json.JSONObject.accumulate(), sfi.director.application.FrontendHTTPServer.auth_login(), sfi.director.application.FrontendHTTPServer.convertException(), sfi.director.application.FrontendHTTPServer.db_decryptpw(), sfi.director.application.FrontendHTTPServer.db_get(), sfi.director.application.FrontendHTTPServer.db_listevents(), sfi.director.application.FrontendHTTPServer.db_searchget(), sfi.director.application.FrontendHTTPServer.db_searchsize(), sfi.director.application.FrontendHTTPServer.edit_data(), sfi.director.application.FrontendHTTPServer.edit_export(), sfi.director.application.FrontendHTTPServer.edit_fields(), sfi.director.application.FrontendHTTPServer.edit_update(), sfi.director.application.FrontendHTTPServer.file_retrieve(), sfi.director.application.FrontendHTTPServer.file_upload(), sfi.director.application.FrontendHTTPServer.handleRpc(), org.json.Test.main(), org.json.JSONObject.put(), org.json.JSONObject.putOpt(), sfi.director.application.FrontendHTTPServer.serve(), sfi.director.application.FrontendHTTPServer.session_create(), sfi.director.application.FrontendHTTPServer.session_enumDomains(), org.json.CookieList.toJSONObject(), org.json.HTTP.toJSONObject(), org.json.Cookie.toJSONObject(), sfi.director.repository.DBObject.toJSONObject(), org.json.JSONArray.toJSONObject(), and sfi.director.application.FrontendHTTPServer.util_logOverview().

JSONObject org.json.JSONObject.put	(	String	key,
		double	value
	)

Put a key/double pair in the JSONObject.

Parameters

key	A key string.
value	A double which is the value.

Returns

this.

References org.json.JSONObject.put().

JSONObject org.json.JSONObject.put	(	String	key,
		int	value
	)

Put a key/int pair in the JSONObject.

Parameters

key	A key string.
value	An int which is the value.

Returns

this.

References org.json.JSONObject.put().

JSONObject org.json.JSONObject.put	(	String	key,
		Object	value
	)		throws NullPointerException

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, String, or the JSONObject.NULL object.

Returns

this.

Exceptions

NullPointerException

The key must be non-null.

JSONObject org.json.JSONObject.putOpt	(	String	key,
		Object	value
	)		throws NullPointerException

Put a key/value pair in the JSONObject, but only if the value is 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, String, or the JSONObject.NULL object.

Returns

this.

Exceptions

NullPointerException

The key must be non-null.

References org.json.JSONObject.put().

Referenced by org.json.JSONObject.JSONObject().

static String org.json.JSONObject.quote ( String  string )

static

Produce a string in double quotes with backslash sequences in all the right places.

Parameters

string

A String

Returns

A String correctly formatted for insertion in a JSON message.

References org.json.JSONObject.length().

Referenced by org.json.JSONObject.get(), org.json.JSONObject.getBoolean(), org.json.JSONObject.getDouble(), org.json.JSONObject.getJSONArray(), org.json.JSONObject.getJSONObject(), and org.json.JSONObject.toString().

Object org.json.JSONObject.remove

(

String

key

)

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.

Referenced by sfi.director.application.FrontendHTTPServer.handleRpc().

JSONArray org.json.JSONObject.toJSONArray

(

JSONArray

names

)

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.

Returns

A JSONArray of values.

References org.json.JSONArray.getString(), org.json.JSONArray.length(), org.json.JSONObject.opt(), and org.json.JSONArray.put().

Referenced by org.json.CDL.toString().

String org.json.JSONObject.toString

(

)

Make an JSON external form string of this JSONObject.

For compactness, no unnecessary whitespace is added.

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).

References org.json.JSONObject.keys(), and org.json.JSONObject.quote().

Referenced by sfi.director.repository.JSONDir.encode(), org.json.JSONObject.getString(), sfi.director.application.FrontendHTTPServer.handleRpc(), org.json.Test.main(), sfi.director.application.FrontendHTTPServer.serve(), org.json.CDL.toString(), and org.json.JSONObject.toString().

String org.json.JSONObject.toString

(

int

indentFactor

)

Make a prettyprinted JSON external form string 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).

References org.json.JSONObject.toString().

Member Data Documentation

final Object org.json.JSONObject.NULL = new Null()

static

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".

Referenced by org.json.JSONObject.isNull(), and org.json.JSONTokener.nextValue().

---

The documentation for this class was generated from the following file:

• director/src/org/json/JSONObject.java