FileDocCategorySizeDatePackage
JSONObject.javaAPI DocAndroid 1.5 API35282Wed May 06 22:41:04 BST 2009org.json

JSONObject

public class JSONObject extends Object
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.
author
JSON.org
version
2

Fields Summary
private HashMap
myHashMap
The hash map where the JSONObject's properties are kept.
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".
Constructors Summary
public JSONObject()
Construct an empty JSONObject.



             
      
        this.myHashMap = new HashMap();
public 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.

param
jo A JSONObject.
param
sa An array of strings.
exception
JSONException If a value is a non-finite number.

        this();
        for (int i = 0; i < sa.length; i += 1) {
            putOpt(sa[i], jo.opt(sa[i]));
        }
public JSONObject(JSONTokener x)
Construct a JSONObject from a JSONTokener.

param
x A JSONTokener object containing the source string.
throws
JSONException If there is a syntax error in the source string.

        this();
        char c;
        String key;

        if (x.nextClean() != '{") {
            throw x.syntaxError("A JSONObject text must begin with '{'");
        }
        for (;;) {
            c = x.nextClean();
            switch (c) {
            case 0:
                throw x.syntaxError("A JSONObject text must end with '}'");
            case '}":
                return;
            default:
                x.back();
                key = x.nextValue().toString();
            }

            /*
             * The key is followed by ':'. We will also tolerate '=' or '=>'.
             */

            c = x.nextClean();
            if (c == '=") {
                if (x.next() != '>") {
                    x.back();
                }
            } else if (c != ':") {
                throw x.syntaxError("Expected a ':' after a key");
            }
            this.myHashMap.put(key, x.nextValue());

            /*
             * Pairs are separated by ','. We will also tolerate ';'.
             */

            switch (x.nextClean()) {
            case ';":
            case ',":
                if (x.nextClean() == '}") {
                    return;
                }
                x.back();
                break;
            case '}":
                return;
            default:
                throw x.syntaxError("Expected a ',' or '}'");
            }
        }
public JSONObject(Map map)
Construct a JSONObject from a Map.

param
map A map object that can be used to initialize the contents of the JSONObject.

        this.myHashMap = new HashMap(map);
public JSONObject(String string)
Construct a JSONObject from a string. This is the most commonly used JSONObject constructor.

param
string A string beginning with { (left brace) and ending with } (right brace).
exception
JSONException If there is a syntax error in the source string.

        this(new JSONTokener(string));
Methods Summary
public org.json.JSONObjectaccumulate(java.lang.String key, java.lang.Object value)
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.

param
key A key string.
param
value An object to be accumulated under the key.
return
this.
throws
JSONException If the value is an invalid number or if the key is null.

        testValidity(value);
        Object o = opt(key);
        if (o == null) {
            put(key, value);
        } else if (o instanceof JSONArray) {
            ((JSONArray)o).put(value);
        } else {
            put(key, new JSONArray().put(o).put(value));
        }
        return this;
public java.lang.Objectget(java.lang.String key)
Get the value object associated with a key.

param
key A key string.
return
The object associated with the key.
throws
JSONException if the key is not found.

        Object o = opt(key);
        if (o == null) {
            throw new JSONException("JSONObject[" + quote(key) + 
                    "] not found.");
        }
        return o;
public booleangetBoolean(java.lang.String key)
Get the boolean value associated with a key.

param
key A key string.
return
The truth.
throws
JSONException if the value is not a Boolean or the String "true" or "false".

        Object o = get(key);
        if (o.equals(Boolean.FALSE) ||
                (o instanceof String &&
                ((String)o).equalsIgnoreCase("false"))) {
            return false;
        } else if (o.equals(Boolean.TRUE) ||
                (o instanceof String &&
                ((String)o).equalsIgnoreCase("true"))) {
            return true;
        }
        throw new JSONException("JSONObject[" + quote(key) + 
                "] is not a Boolean.");
public doublegetDouble(java.lang.String key)
Get the double value associated with a key.

param
key A key string.
return
The numeric value.
throws
JSONException if the key is not found or if the value is not a Number object and cannot be converted to a number.

        Object o = get(key);
        try {
            return o instanceof Number ? 
                    ((Number)o).doubleValue() : Double.parseDouble((String)o);
        } catch (Exception e) {
            throw new JSONException("JSONObject[" + quote(key) + 
                "] is not a number.");
        }
public intgetInt(java.lang.String key)
Get the int value associated with a key. If the number value is too large for an int, it will be clipped.

param
key A key string.
return
The integer value.
throws
JSONException if the key is not found or if the value cannot be converted to an integer.

        Object o = get(key);
        return o instanceof Number ? 
                ((Number)o).intValue() : (int)getDouble(key);
public org.json.JSONArraygetJSONArray(java.lang.String key)
Get the JSONArray value associated with a key.

param
key A key string.
return
A JSONArray which is the value.
throws
JSONException if the key is not found or if the value is not a JSONArray.

        Object o = get(key);
        if (o instanceof JSONArray) {
            return (JSONArray)o;
        }
        throw new JSONException("JSONObject[" + quote(key) + 
                "] is not a JSONArray.");
public org.json.JSONObjectgetJSONObject(java.lang.String key)
Get the JSONObject value associated with a key.

param
key A key string.
return
A JSONObject which is the value.
throws
JSONException if the key is not found or if the value is not a JSONObject.

        Object o = get(key);
        if (o instanceof JSONObject) {
            return (JSONObject)o;
        }
        throw new JSONException("JSONObject[" + quote(key) + 
                "] is not a JSONObject.");
public longgetLong(java.lang.String key)
Get the long value associated with a key. If the number value is too long for a long, it will be clipped.

param
key A key string.
return
The long value.
throws
JSONException if the key is not found or if the value cannot be converted to a long.

        Object o = get(key);
        return o instanceof Number ? 
                ((Number)o).longValue() : (long)getDouble(key);
public java.lang.StringgetString(java.lang.String key)
Get the string associated with a key.

param
key A key string.
return
A string which is the value.
throws
JSONException if the key is not found.

        return get(key).toString();
public booleanhas(java.lang.String key)
Determine if the JSONObject contains a specific key.

param
key A key string.
return
true if the key exists in the JSONObject.

        return this.myHashMap.containsKey(key);
public booleanisNull(java.lang.String key)
Determine if the value associated with the key is null or if there is no value.

param
key A key string.
return
true if there is no value associated with the key or if the value is the JSONObject.NULL object.

        return JSONObject.NULL.equals(opt(key));
public java.util.Iteratorkeys()
Get an enumeration of the keys of the JSONObject.

return
An iterator of the keys.

        return this.myHashMap.keySet().iterator();
public intlength()
Get the number of keys stored in the JSONObject.

return
The number of keys in the JSONObject.

        return this.myHashMap.size();
public org.json.JSONArraynames()
Produce a JSONArray containing the names of the elements of this JSONObject.

return
A JSONArray containing the key strings, or null if the JSONObject is empty.

        JSONArray ja = new JSONArray();
        Iterator  keys = keys();
        while (keys.hasNext()) {
            ja.put(keys.next());
        }
        return ja.length() == 0 ? null : ja;
public static java.lang.StringnumberToString(java.lang.Number n)
Produce a string from a number.

param
n A Number
return
A String.
throws
JSONException If n is a non-finite number.

        if (n == null) {
            throw new JSONException("Null pointer");
        }
        testValidity(n);

// Shave off trailing zeros and decimal point, if possible.

        String s = n.toString();
        if (s.indexOf('.") > 0 && s.indexOf('e") < 0 && s.indexOf('E") < 0) {
            while (s.endsWith("0")) {
                s = s.substring(0, s.length() - 1);
            }
            if (s.endsWith(".")) {
                s = s.substring(0, s.length() - 1);
            }
        }
        return s;
public java.lang.Objectopt(java.lang.String key)
Get an optional value associated with a key.

param
key A key string.
return
An object which is the value, or null if there is no value.

        return key == null ? null : this.myHashMap.get(key);
public booleanoptBoolean(java.lang.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".

param
key A key string.
return
The truth.

        return optBoolean(key, false);
public booleanoptBoolean(java.lang.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).

param
key A key string.
param
defaultValue The default.
return
The truth.

        try {
            return getBoolean(key);
        } catch (Exception e) {
            return defaultValue;
        }
public doubleoptDouble(java.lang.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.

param
key A string which is the key.
return
An object which is the value.

        return optDouble(key, Double.NaN);
public doubleoptDouble(java.lang.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.

param
key A key string.
param
defaultValue The default.
return
An object which is the value.

        try {
            Object o = opt(key);
            return o instanceof Number ? ((Number)o).doubleValue() :
                new Double((String)o).doubleValue();
        } catch (Exception e) {
            return defaultValue;
        }
public intoptInt(java.lang.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.

param
key A key string.
return
An object which is the value.

        return optInt(key, 0);
public intoptInt(java.lang.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.

param
key A key string.
param
defaultValue The default.
return
An object which is the value.

        try {
            return getInt(key);
        } catch (Exception e) {
            return defaultValue;
        }
public org.json.JSONArrayoptJSONArray(java.lang.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.

param
key A key string.
return
A JSONArray which is the value.

        Object o = opt(key);
        return o instanceof JSONArray ? (JSONArray)o : null;
public org.json.JSONObjectoptJSONObject(java.lang.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.

param
key A key string.
return
A JSONObject which is the value.

        Object o = opt(key);
        return o instanceof JSONObject ? (JSONObject)o : null;
public longoptLong(java.lang.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.

param
key A key string.
return
An object which is the value.

        return optLong(key, 0);
public longoptLong(java.lang.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.

param
key A key string.
param
defaultValue The default.
return
An object which is the value.

        try {
            return getLong(key);
        } catch (Exception e) {
            return defaultValue;
        }
public java.lang.StringoptString(java.lang.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.

param
key A key string.
return
A string which is the value.

        return optString(key, "");
public java.lang.StringoptString(java.lang.String key, java.lang.String defaultValue)
Get an optional string associated with a key. It returns the defaultValue if there is no such key.

param
key A key string.
param
defaultValue The default.
return
A string which is the value.

        Object o = opt(key);
        return o != null ? o.toString() : defaultValue;
public org.json.JSONObjectput(java.lang.String key, boolean value)
Put a key/boolean pair in the JSONObject.

param
key A key string.
param
value A boolean which is the value.
return
this.
throws
JSONException If the key is null.

        put(key, Boolean.valueOf(value));
        return this;
public org.json.JSONObjectput(java.lang.String key, double value)
Put a key/double pair in the JSONObject.

param
key A key string.
param
value A double which is the value.
return
this.
throws
JSONException If the key is null or if the number is invalid.

        put(key, new Double(value));
        return this;
public org.json.JSONObjectput(java.lang.String key, int value)
Put a key/int pair in the JSONObject.

param
key A key string.
param
value An int which is the value.
return
this.
throws
JSONException If the key is null.

        put(key, new Integer(value));
        return this;
public org.json.JSONObjectput(java.lang.String key, long value)
Put a key/long pair in the JSONObject.

param
key A key string.
param
value A long which is the value.
return
this.
throws
JSONException If the key is null.

        put(key, new Long(value));
        return this;
public org.json.JSONObjectput(java.lang.String key, java.lang.Object 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.

param
key A key string.
param
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.
return
this.
throws
JSONException If the value is non-finite number or if the key is null.

        if (key == null) {
            throw new JSONException("Null key.");
        }
        if (value != null) {
            testValidity(value);
            this.myHashMap.put(key, value);
        } else {
            remove(key);
        }
        return this;
public org.json.JSONObjectputOpt(java.lang.String key, java.lang.Object value)
Put a key/value pair in the JSONObject, but only if the key and the value are both non-null.

param
key A key string.
param
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.
return
this.
throws
JSONException If the value is a non-finite number.

        if (key != null && value != null) {
            put(key, value);
        }
        return this;
public static java.lang.Stringquote(java.lang.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.

param
string A String
return
A String correctly formatted for insertion in a JSON text.

        if (string == null || string.length() == 0) {
            return "\"\"";
        }

        char         b;
        char         c = 0;
        int          i;
        int          len = string.length();
        StringBuilder sb = new StringBuilder(len + 4);
        String       t;

        sb.append('"");
        for (i = 0; i < len; i += 1) {
            b = c;
            c = string.charAt(i);
            switch (c) {
            case '\\":
            case '"":
                sb.append('\\");
                sb.append(c);
                break;
            case '/":
                if (b == '<") {
                    sb.append('\\");
                }
                sb.append(c);
                break;
            case '\b":
                sb.append("\\b");
                break;
            case '\t":
                sb.append("\\t");
                break;
            case '\n":
                sb.append("\\n");
                break;
            case '\f":
                sb.append("\\f");
                break;
            case '\r":
                sb.append("\\r");
                break;
            default:
                if (c < ' ") {
                    t = "000" + Integer.toHexString(c);
                    sb.append("\\u" + t.substring(t.length() - 4));
                } else {
                    sb.append(c);
                }
            }
        }
        sb.append('"");
        return sb.toString();
public java.lang.Objectremove(java.lang.String key)
Remove a name and its value, if present.

param
key The name to be removed.
return
The value that was associated with the name, or null if there was no value.

        return this.myHashMap.remove(key);
static voidtestValidity(java.lang.Object o)
Throw an exception if the object is an NaN or infinite number.

param
o The object to test.
throws
JSONException If o is a non-finite number.

        if (o != null) {
            if (o instanceof Double) {
                if (((Double)o).isInfinite() || ((Double)o).isNaN()) {
                    throw new JSONException(
                        "JSON does not allow non-finite numbers");
                }
            } else if (o instanceof Float) {
                if (((Float)o).isInfinite() || ((Float)o).isNaN()) {
                    throw new JSONException(
                        "JSON does not allow non-finite numbers.");
                }
            }
        }
public org.json.JSONArraytoJSONArray(org.json.JSONArray names)
Produce a JSONArray containing the values of the members of this JSONObject.

param
names A JSONArray containing a list of key strings. This determines the sequence of the values in the result.
return
A JSONArray of values.
throws
JSONException If any of the values are non-finite numbers.

        if (names == null || names.length() == 0) {
            return null;
        }
        JSONArray ja = new JSONArray();
        for (int i = 0; i < names.length(); i += 1) {
            ja.put(this.opt(names.getString(i)));
        }
        return ja;
public java.lang.StringtoString()
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.

return
a printable, displayable, portable, transmittable representation of the object, beginning with { (left brace) and ending with } (right brace).

        try {
            Iterator     keys = keys();
            StringBuilder sb = new StringBuilder("{");
    
            while (keys.hasNext()) {
                if (sb.length() > 1) {
                    sb.append(',");
                }
                Object o = keys.next();
                sb.append(quote(o.toString()));
                sb.append(':");
                sb.append(valueToString(this.myHashMap.get(o)));
            }
            sb.append('}");
            return sb.toString();
        } catch (Exception e) {
            return null;
        }
public java.lang.StringtoString(int indentFactor)
Make a prettyprinted JSON text of this JSONObject.

Warning: This method assumes that the data structure is acyclical.

param
indentFactor The number of spaces to add to each level of indentation.
return
a printable, displayable, portable, transmittable representation of the object, beginning with { (left brace) and ending with } (right brace).
throws
JSONException If the object contains an invalid number.

        return toString(indentFactor, 0);
java.lang.StringtoString(int indentFactor, int indent)
Make a prettyprinted JSON text of this JSONObject.

Warning: This method assumes that the data structure is acyclical.

param
indentFactor The number of spaces to add to each level of indentation.
param
indent The indentation of the top level.
return
a printable, displayable, transmittable representation of the object, beginning with { (left brace) and ending with } (right brace).
throws
JSONException If the object contains an invalid number.

        int          i;
        int          n = length();
        if (n == 0) {
            return "{}";
        }
        Iterator     keys = keys();
        StringBuilder sb = new StringBuilder("{");
        int          newindent = indent + indentFactor;
        Object       o;
        if (n == 1) {
            o = keys.next();
            sb.append(quote(o.toString()));
            sb.append(": ");
            sb.append(valueToString(this.myHashMap.get(o), indentFactor, 
                    indent));
        } else {
            while (keys.hasNext()) {
                o = keys.next();
                if (sb.length() > 1) {
                    sb.append(",\n");
                } else {
                    sb.append('\n");
                }
                for (i = 0; i < newindent; i += 1) {
                    sb.append(' ");
                }
                sb.append(quote(o.toString()));
                sb.append(": ");
                sb.append(valueToString(this.myHashMap.get(o), indentFactor,
                        newindent));
            }
            if (sb.length() > 1) {
                sb.append('\n");
                for (i = 0; i < indent; i += 1) {
                    sb.append(' ");
                }
            }
        }
        sb.append('}");
        return sb.toString();
static java.lang.StringvalueToString(java.lang.Object value)
Make a JSON text of an object value.

Warning: This method assumes that the data structure is acyclical.

param
value The value to be serialized.
return
a printable, displayable, transmittable representation of the object, beginning with { (left brace) and ending with } (right brace).
throws
JSONException If the value is or contains an invalid number.

        if (value == null || value.equals(null)) {
            return "null";
        }
        if (value instanceof Number) {
            return numberToString((Number) value);
        }
        if (value instanceof Boolean || value instanceof JSONObject ||
                value instanceof JSONArray) {
            return value.toString();
        }
        return quote(value.toString());
static java.lang.StringvalueToString(java.lang.Object value, int indentFactor, int indent)
Make a prettyprinted JSON text of an object value.

Warning: This method assumes that the data structure is acyclical.

param
value The value to be serialized.
param
indentFactor The number of spaces to add to each level of indentation.
param
indent The indentation of the top level.
return
a printable, displayable, transmittable representation of the object, beginning with { (left brace) and ending with } (right brace).
throws
JSONException If the object contains an invalid number.

        if (value == null || value.equals(null)) {
            return "null";
        }
        if (value instanceof Number) {
            return numberToString((Number) value);
        }
        if (value instanceof Boolean) {
            return value.toString();
        }
        if (value instanceof JSONObject) {
            return ((JSONObject)value).toString(indentFactor, indent);
        }
        if (value instanceof JSONArray) {
            return ((JSONArray)value).toString(indentFactor, indent);
        }
        return quote(value.toString());