Expand Minimize Picture-in-picture Power Device Status Voice Recognition Skip Back Skip Forward Minus Plus Play Search
Documentation
Sidebar

Class JSONObject

Hierarchy

java.lang.Object

Package
org.json

Overview

A modifiable set of name/value mappings. Names are unique, non-null strings. Values may be any mix of {@link JSONObject JSONObjects}, {@link JSONArray JSONArrays}, Strings, Booleans, Integers, Longs, Doubles or {@link #NULL}. Values may not be {@code null}, {@link Double#isNaN() NaNs}, {@link Double#isInfinite() infinities}, or of any type not listed here.

This class can coerce values to another type when requested.

This class can look up both mandatory and optional values:

  • Use getType() to retrieve a mandatory value. This fails with a {@code 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 {@code null} reference, and the sentinel value {@link JSONObject#NULL}. In particular, calling {@code put(name, null)} removes the named entry from the object but {@code put(name, JSONObject.NULL)} stores an entry whose value is {@code 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.

Fields

NULL

public static final java.lang.Object NULL

Constructors

JSONObject()

Creates a {@code JSONObject} with no name/value mappings.

public JSONObject()

JSONObject( java.util.Map copyFrom )

Creates a new {@code JSONObject} by copying all name/value mappings from the given map.

public JSONObject(java.util.Map copyFrom)

Parameters

copyFrom
a map whose keys are of type {@link String} and whose values are of supported types.

JSONObject( JSONTokener readFrom )

Creates a new {@code JSONObject} with name/value mappings from the next object in the tokener.

public JSONObject(JSONTokener readFrom)

Parameters

readFrom
a tokener whose nextValue() method will yield a {@code JSONObject}.

JSONObject( String json )

Creates a new {@code JSONObject} with name/value mappings from the JSON string.

public JSONObject(String json)

Parameters

json
a JSON-encoded string containing an object.

JSONObject( JSONObject copyFrom, java.lang.String[] names )

Creates a new {@code JSONObject} by copying mappings for the listed names from the given object. Names that aren't present in {@code copyFrom} will be skipped.

public JSONObject(JSONObject copyFrom,java.lang.String[] names)

Parameters

copyFrom
names

Methods

length()

Returns the number of name/value mappings in this object.

public int length()

put( String name, boolean value )

Maps {@code name} to {@code value}, clobbering any existing name/value mapping with the same name.

public org.json.JSONObject put(String name,boolean value) throws org.json.JSONException

Parameters

name
value

Throws

put( String name, double value )

Maps {@code name} to {@code value}, clobbering any existing name/value mapping with the same name.

public org.json.JSONObject put(String name,double value) throws org.json.JSONException

Parameters

name
value
a finite value. May not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite() infinities}.

Throws

put( String name, int value )

Maps {@code name} to {@code value}, clobbering any existing name/value mapping with the same name.

public org.json.JSONObject put(String name,int value) throws org.json.JSONException

Parameters

name
value

Throws

put( String name, long value )

Maps {@code name} to {@code value}, clobbering any existing name/value mapping with the same name.

public org.json.JSONObject put(String name,long value) throws org.json.JSONException

Parameters

name
value

Throws

put( String name, Object value )

Maps {@code name} to {@code value}, clobbering any existing name/value mapping with the same name. If the value is {@code null}, any existing mapping for {@code name} is removed.

public org.json.JSONObject put(String name,Object value) throws org.json.JSONException

Parameters

name
value
a {@link JSONObject}, {@link JSONArray}, String, Boolean, Integer, Long, Double, {@link #NULL}, or {@code null}. May not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite() infinities}.

Throws

putOpt( String name, Object value )

Equivalent to {@code put(name, value)} when both parameters are non-null; does nothing otherwise.

public org.json.JSONObject putOpt(String name,Object value) throws org.json.JSONException

Parameters

name
value

Throws

accumulate( String name, Object value )

Appends {@code value} to the array already mapped to {@code name}. If this object has no mapping for {@code name}, this inserts a new mapping. If the mapping exists but its value is not an array, the existing and new values are inserted in order into a new array which is itself mapped to {@code name}. In aggregate, this allows values to be added to a mapping one at a time.

Note that {@code append(String, Object)} provides better semantics. In particular, the mapping for {@code name} will always be a JSONArray. Using {@code accumulate} will result in either a JSONArray or a mapping whose type is the type of {@code value} depending on the number of calls to it.

public org.json.JSONObject accumulate(String name,Object value) throws org.json.JSONException

Parameters

name
value
a {@link JSONObject}, {@link JSONArray}, String, Boolean, Integer, Long, Double, {@link #NULL} or null. May not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite() infinities}.

Throws

append( String name, Object value )

Appends values to the array mapped to {@code name}. A new JSONArray mapping for {@code name} will be inserted if no mapping exists. If the existing mapping for {@code name} is not a JSONArray, a JSONException will be thrown.

public org.json.JSONObject append(String name,Object value) throws org.json.JSONException

Parameters

name
value

Throws

remove( String name )

Removes the named mapping if it exists; does nothing otherwise.

public java.lang.Object remove(String name)

Parameters

name

isNull( String name )

Returns true if this object has no mapping for {@code name} or if it has a mapping whose value is {@link #NULL}.

public boolean isNull(String name)

Parameters

name

has( String name )

Returns true if this object has a mapping for {@code name}. The mapping may be {@link #NULL}.

public boolean has(String name)

Parameters

name

get( String name )

Returns the value mapped by {@code name}, or throws if no such mapping exists.

public java.lang.Object get(String name) throws org.json.JSONException

Parameters

name

Throws

opt( String name )

Returns the value mapped by {@code name}, or null if no such mapping exists.

public java.lang.Object opt(String name)

Parameters

name

getBoolean( String name )

Returns the value mapped by {@code name} if it exists and is a boolean or can be coerced to a boolean, or throws otherwise.

public boolean getBoolean(String name) throws org.json.JSONException

Parameters

name

Throws

optBoolean( String name )

Returns the value mapped by {@code name} if it exists and is a boolean or can be coerced to a boolean, or false otherwise.

public boolean optBoolean(String name)

Parameters

name

optBoolean( String name, boolean fallback )

Returns the value mapped by {@code name} if it exists and is a boolean or can be coerced to a boolean, or {@code fallback} otherwise.

public boolean optBoolean(String name,boolean fallback)

Parameters

name
fallback

getDouble( String name )

Returns the value mapped by {@code name} if it exists and is a double or can be coerced to a double, or throws otherwise.

public double getDouble(String name) throws org.json.JSONException

Parameters

name

Throws

optDouble( String name )

Returns the value mapped by {@code name} if it exists and is a double or can be coerced to a double, or {@code NaN} otherwise.

public double optDouble(String name)

Parameters

name

optDouble( String name, double fallback )

Returns the value mapped by {@code name} if it exists and is a double or can be coerced to a double, or {@code fallback} otherwise.

public double optDouble(String name,double fallback)

Parameters

name
fallback

getInt( String name )

Returns the value mapped by {@code name} if it exists and is an int or can be coerced to an int, or throws otherwise.

public int getInt(String name) throws org.json.JSONException

Parameters

name

Throws

optInt( String name )

Returns the value mapped by {@code name} if it exists and is an int or can be coerced to an int, or 0 otherwise.

public int optInt(String name)

Parameters

name

optInt( String name, int fallback )

Returns the value mapped by {@code name} if it exists and is an int or can be coerced to an int, or {@code fallback} otherwise.

public int optInt(String name,int fallback)

Parameters

name
fallback

getLong( String name )

Returns the value mapped by {@code name} if it exists and is a long or can be coerced to a long, or throws otherwise. Note that JSON represents numbers as doubles, so this is lossy; use strings to transfer numbers via JSON.

public long getLong(String name) throws org.json.JSONException

Parameters

name

Throws

optLong( String name )

Returns the value mapped by {@code name} if it exists and is a long or can be coerced to a long, or 0 otherwise. Note that JSON represents numbers as doubles, so this is lossy; use strings to transfer numbers via JSON.

public long optLong(String name)

Parameters

name

optLong( String name, long fallback )

Returns the value mapped by {@code name} if it exists and is a long or can be coerced to a long, or {@code fallback} otherwise. Note that JSON represents numbers as doubles, so this is lossy; use strings to transfer numbers via JSON.

public long optLong(String name,long fallback)

Parameters

name
fallback

getString( String name )

Returns the value mapped by {@code name} if it exists, coercing it if necessary, or throws if no such mapping exists.

public java.lang.String getString(String name) throws org.json.JSONException

Parameters

name

Throws

optString( String name )

Returns the value mapped by {@code name} if it exists, coercing it if necessary, or the empty string if no such mapping exists.

public java.lang.String optString(String name)

Parameters

name

optString( String name, String fallback )

Returns the value mapped by {@code name} if it exists, coercing it if necessary, or {@code fallback} if no such mapping exists.

public java.lang.String optString(String name,String fallback)

Parameters

name
fallback

getJSONArray( String name )

Returns the value mapped by {@code name} if it exists and is a {@code JSONArray}, or throws otherwise.

public org.json.JSONArray getJSONArray(String name) throws org.json.JSONException

Parameters

name

Throws

optJSONArray( String name )

Returns the value mapped by {@code name} if it exists and is a {@code JSONArray}, or null otherwise.

public org.json.JSONArray optJSONArray(String name)

Parameters

name

getJSONObject( String name )

Returns the value mapped by {@code name} if it exists and is a {@code JSONObject}, or throws otherwise.

public org.json.JSONObject getJSONObject(String name) throws org.json.JSONException

Parameters

name

Throws

optJSONObject( String name )

Returns the value mapped by {@code name} if it exists and is a {@code JSONObject}, or null otherwise.

public org.json.JSONObject optJSONObject(String name)

Parameters

name

toJSONArray( JSONArray names )

Returns an array with the values corresponding to {@code names}. The array contains null for names that aren't mapped. This method returns null if {@code names} is either null or empty.

public org.json.JSONArray toJSONArray(JSONArray names) throws org.json.JSONException

Parameters

names

Throws

keys()

Returns an iterator of the {@code String} names in this object. The returned iterator supports {@link Iterator#remove() remove}, which will remove the corresponding mapping from this object. If this object is modified after the iterator is returned, the iterator's behavior is undefined. The order of the keys is undefined.

public java.util.Iterator keys()

keySet()

Returns the set of {@code String} names in this object. The returned set is a view of the keys in this object. {@link Set#remove(Object)} will remove the corresponding mapping from this object and set iterator behaviour is undefined if this object is modified after it is returned. See {@link #keys()}.

public java.util.Set keySet()

names()

Returns an array containing the string names in this object. This method returns null if this object contains no mappings.

public org.json.JSONArray names()

toString()

Encodes this object as a compact JSON string, such as:

{"query":"Pizza","locations":[94043,90210]}

public java.lang.String toString()

toString( int indentSpaces )

Encodes this object as a human readable JSON string for debugging, such as:

 {
     "query": "Pizza",
     "locations": [
         94043,
         90210
     ]
 }

public java.lang.String toString(int indentSpaces) throws org.json.JSONException

Parameters

indentSpaces
the number of spaces to indent for each level of nesting.

Throws

numberToString( Number number )

Encodes the number as a JSON string.

public static java.lang.String numberToString(Number number) throws org.json.JSONException

Parameters

number
a finite value. May not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite() infinities}.

Throws

quote( String data )

Encodes {@code data} as a JSON string. This applies quotes and any necessary character escaping.

public static java.lang.String quote(String data)

Parameters

data
the string to encode. Null will be interpreted as an empty string.

wrap( Object o )

Wraps the given object if necessary.

If the object is null or , returns {@link #NULL}. If the object is a {@code JSONArray} or {@code JSONObject}, no wrapping is necessary. If the object is {@code NULL}, no wrapping is necessary. If the object is an array or {@code Collection}, returns an equivalent {@code JSONArray}. If the object is a {@code Map}, returns an equivalent {@code JSONObject}. If the object is a primitive wrapper type or {@code String}, returns the object. Otherwise if the object is from a {@code java} package, returns the result of {@code toString}. If wrapping fails, returns null.

public static java.lang.Object wrap(Object o)

Parameters

o

Inherited Methods

From Class Methods
java.lang.Object getClass, hashCode, equals, clone, toString, notify, notifyAll, wait, wait, wait, finalize
View on GitHub.com
Previous Section Next Section