## org.codehaus.groovy.grails.web.json
Class JSONObject

    java.lang.Object
      org.codehaus.groovy.grails.web.json.JSONObject

All Implemented Interfaces:
  Map, JSONElement

    public class JSONObject

extends Object
implements JSONElement, Map

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.

Version:
  2
Author:
  JSON.org

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map
`Map.Entry<K,V>`

Field Summary
`static Object` `NULL` It is sometimes more convenient and less ambiguous to have a `NULL` object than to use Java's `null` value.

Constructor Summary
`JSONObject()` Construct an empty JSONObject.
`JSONObject(JSONObject jo, String[] sa)` Construct a JSONObject from a subset of another JSONObject.
`JSONObject(JSONTokener x)` Construct a JSONObject from a JSONTokener.
`JSONObject(Map map)` Construct a JSONObject from a Map.
`JSONObject(String string)` Construct a JSONObject from a string.

Method Summary
`JSONObject` `accumulate(String key, Object value)` Accumulate values under a key.
`void` `clear()`
`boolean` `containsKey(Object o)`
`boolean` `containsValue(Object o)`
`static String` `dateToString(Date d)`
`Set` `entrySet()`
`boolean` `equals(Object o)`
`Object` `get(Object o)`
`Object` `get(String key)` Get the value object associated with a key.
`boolean` `getBoolean(String key)` Get the boolean value associated with a key.
`double` `getDouble(String key)` Get the double value associated with a key.
`int` `getInt(String key)` Get the int value associated with a key.
`JSONArray` `getJSONArray(String key)` Get the JSONArray value associated with a key.
`JSONObject` `getJSONObject(String key)` Get the JSONObject value associated with a key.
`long` `getLong(String key)` Get the long value associated with a key.
`String` `getString(String key)` Get the string associated with a key.
`boolean` `has(String key)` Determine if the JSONObject contains a specific key.
`int` `hashCode()`
`boolean` `isEmpty()`
`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.
`Set` `keySet()`
`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.
`static String` `numberToString(Number n)` Produce a string from a number.
`Object` `opt(String key)` 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.
`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.
`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.
`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.
`Object` `put(Object o, Object o1)`
`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, long value)` Put a key/long pair in the JSONObject.
`JSONObject` `put(String key, Object value)` Put a key/value pair in the JSONObject.
`void` `putAll(Map map)`
`JSONObject` `putOpt(String key, Object value)` Put a key/value pair in the JSONObject, but only if the key and the value are both non-null.
`static String` `quote(String string)` Produce a string in double quotes with backslash sequences in all the right places.
`Object` `remove(Object o)`
`Object` `remove(String key)` Remove a name and its value, if present.
`int` `size()`
`(package private) static void` `testValidity(Object o)` Throw an exception if the object is an NaN or infinite number.
`JSONArray` `toJSONArray(JSONArray names)` Produce a JSONArray containing the values of the members of this JSONObject.
`String` `toString()` Make an JSON text of this JSONObject.
`String` `toString(int indentFactor)` Make a prettyprinted JSON text of this JSONObject.
`(package private) String` `toString(int indentFactor, int indent)` Make a prettyprinted JSON text of this JSONObject.
`Collection` `values()`
`(package private) static String` `valueToString(Object value)` Make a JSON text of an object value.
`(package private) static String` `valueToString(Object value, int indentFactor, int indent)` Make a prettyprinted JSON text of an object value.
`Writer` `write(Writer writer)` Write the contents of the JSONObject as JSON text to a writer.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### NULL

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

Constructor Detail

### JSONObject

    public JSONObject()

  Construct an empty JSONObject.

### JSONObject

    public JSONObject(JSONObject jo,
                      String[] sa)
               throws JSONException

  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.
  Throws:
    `JSONException` - If a value is a non-finite number.

### JSONObject

    public JSONObject(JSONTokener x)
               throws JSONException

  Construct a JSONObject from a JSONTokener.

  Parameters:
    `x` - A JSONTokener object containing the source string.
  Throws:
    `JSONException` - If there is a syntax error in the source string.

### JSONObject

    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.

### JSONObject

    public JSONObject(String string)
               throws JSONException

  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).
  Throws:
    `JSONException` - If there is a syntax error in the source string.

Method Detail

### accumulate

    public JSONObject accumulate(String key,
                                 Object value)
                          throws JSONException

  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.
  Throws:
    `JSONException` - If the value is an invalid number or if the key is null.

### get

    public Object get(String key)
               throws JSONException

  Get the value object associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    The object associated with the key.
  Throws:
    `JSONException` - if the key is not found.

### getBoolean

    public boolean getBoolean(String key)
                       throws JSONException

  Get the boolean value associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    The truth.
  Throws:
    `JSONException` - if the value is not a Boolean or the String "true" or "false".

### getDouble

    public double getDouble(String key)
                     throws JSONException

  Get the double value associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    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.

### getInt

    public int getInt(String key)
               throws JSONException

  Get the int value associated with a key. If the number value is too large for an int, it will be clipped.

  Parameters:
    `key` - A key string.
  Returns:
    The integer value.
  Throws:
    `JSONException` - if the key is not found or if the value cannot be converted to an integer.

### getJSONArray

    public JSONArray getJSONArray(String key)
                           throws JSONException

  Get the JSONArray value associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    A JSONArray which is the value.
  Throws:
    `JSONException` - if the key is not found or if the value is not a JSONArray.

### getJSONObject

    public JSONObject getJSONObject(String key)
                             throws JSONException

  Get the JSONObject value associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    A JSONObject which is the value.
  Throws:
    `JSONException` - if the key is not found or if the value is not a JSONObject.

### getLong

    public long getLong(String key)
                 throws JSONException

  Get the long value associated with a key. If the number value is too long for a long, it will be clipped.

  Parameters:
    `key` - A key string.
  Returns:
    The long value.
  Throws:
    `JSONException` - if the key is not found or if the value cannot be converted to a long.

### getString

    public String getString(String key)
                     throws JSONException

  Get the string associated with a key.

  Parameters:
    `key` - A key string.
  Returns:
    A string which is the value.
  Throws:
    `JSONException` - if the key is not found.

### has

    public boolean 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.

### isNull

    public boolean 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.

### keys

    public Iterator keys()

  Get an enumeration of the keys of the JSONObject.

  Returns:
    An iterator of the keys.

### length

    public int length()

  Get the number of keys stored in the JSONObject.

  Returns:
    The number of keys in the JSONObject.

### names

    public JSONArray 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.

### numberToString

    public static String numberToString(Number n)
                                 throws JSONException

  Produce a string from a number.

  Parameters:
    `n` - A Number
  Returns:
    A String.
  Throws:
    `JSONException` - If n is a non-finite number.

### dateToString

    public static String dateToString(Date d)
                               throws JSONException

  Throws:
    `JSONException`

### opt

    public Object opt(String key)

  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.

### optBoolean

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

  Parameters:
    `key` - A key string.
  Returns:
    The truth.

### optBoolean

    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.
  Returns:
    The truth.

### optDouble

    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.

### optDouble

    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.

### optInt

    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.

  Parameters:
    `key` - A key string.
  Returns:
    An object which is the value.

### optInt

    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.

### optJSONArray

    public JSONArray 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.

### optJSONObject

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

### optLong

    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.

  Parameters:
    `key` - A key string.
  Returns:
    An object which is the value.

### optLong

    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.

### optString

    public String 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.

### optString

    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.

### put

    public JSONObject put(String key,
                          boolean value)
                   throws JSONException

  Put a key/boolean pair in the JSONObject.

  Parameters:
    `key` - A key string.
    `value` - A boolean which is the value.
  Returns:
    this.
  Throws:
    `JSONException` - If the key is null.

### put

    public JSONObject put(String key,
                          double value)
                   throws JSONException

  Put a key/double pair in the JSONObject.

  Parameters:
    `key` - A key string.
    `value` - A double which is the value.
  Returns:
    this.
  Throws:
    `JSONException` - If the key is null or if the number is invalid.

### put

    public JSONObject put(String key,
                          int value)
                   throws JSONException

  Put a key/int pair in the JSONObject.

  Parameters:
    `key` - A key string.
    `value` - An int which is the value.
  Returns:
    this.
  Throws:
    `JSONException` - If the key is null.

### put

    public JSONObject put(String key,
                          long value)
                   throws JSONException

  Put a key/long pair in the JSONObject.

  Parameters:
    `key` - A key string.
    `value` - A long which is the value.
  Returns:
    this.
  Throws:
    `JSONException` - If the key is null.

### put

    public JSONObject put(String key,
                          Object value)
                   throws JSONException

  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:
    `JSONException` - If the value is non-finite number or if the key is null.

### putOpt

    public JSONObject putOpt(String key,
                             Object value)
                      throws JSONException

  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.
  Returns:
    this.
  Throws:
    `JSONException` - If the value is a non-finite number.

### quote

    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
  Parameters:
    `string` - A String
  Returns:
    A String correctly formatted for insertion in a JSON text.

### remove

    public Object 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.

### testValidity

    static void testValidity(Object o)
                      throws JSONException

  Throw an exception if the object is an NaN or infinite number.

  Parameters:
    `o` - The object to test.
  Throws:
    `JSONException` - If o is a non-finite number.

### toJSONArray

    public JSONArray toJSONArray(JSONArray names)
                          throws JSONException

  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.
  Throws:
    `JSONException` - If any of the values are non-finite numbers.

### toString

    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.

  Overrides:
    `toString` in class `Object`
  Returns:
    a printable, displayable, portable, transmittable representation of the object, beginning with `{` (left brace) and ending with `}` (right brace).

### toString

    public String toString(int indentFactor)
                    throws JSONException

  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:
    `JSONException` - If the object contains an invalid number.

### toString

    String toString(int indentFactor,
                    int indent)
              throws JSONException

  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.
    `indent` - The indentation of the top level.
  Returns:
    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.

### valueToString

    static String valueToString(Object value)
                         throws JSONException

  Make a JSON text of an object value.

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

  Parameters:
    `value` - The value to be serialized.
  Returns:
    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.

### valueToString

    static String valueToString(Object value,
                                int indentFactor,
                                int indent)
                         throws JSONException

  Make a prettyprinted JSON text of an object value.

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

  Parameters:
    `value` - The value to be serialized.
    `indentFactor` - The number of spaces to add to each level of indentation.
    `indent` - The indentation of the top level.
  Returns:
    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.

### write

    public Writer write(Writer writer)
                 throws JSONException

  Write the contents of the JSONObject as JSON text to a writer. For compactness, no whitespace is added.

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

  Returns:
    The writer.
  Throws:
    `JSONException`

### size

    public int size()

  Specified by:
    `size` in interface `Map`

### isEmpty

    public boolean isEmpty()

  Specified by:
    `isEmpty` in interface `Map`

### containsKey

    public boolean containsKey(Object o)

  Specified by:
    `containsKey` in interface `Map`

### containsValue

    public boolean containsValue(Object o)

  Specified by:
    `containsValue` in interface `Map`

### get

    public Object get(Object o)

  Specified by:
    `get` in interface `Map`

### put

    public Object put(Object o,
                      Object o1)

  Specified by:
    `put` in interface `Map`

### remove

    public Object remove(Object o)

  Specified by:
    `remove` in interface `Map`

### putAll

    public void putAll(Map map)

  Specified by:
    `putAll` in interface `Map`

### clear

    public void clear()

  Specified by:
    `clear` in interface `Map`

### keySet

    public Set keySet()

  Specified by:
    `keySet` in interface `Map`

### values

    public Collection values()

  Specified by:
    `values` in interface `Map`

### entrySet

    public Set entrySet()

  Specified by:
    `entrySet` in interface `Map`

### equals

    public boolean equals(Object o)

  Specified by:
    `equals` in interface `Map`
  Overrides:
    `equals` in class `Object`

### hashCode

    public int hashCode()

  Specified by:
    `hashCode` in interface `Map`
  Overrides:
    `hashCode` in class `Object`

Copyright (c) 2005-2009 The Grails project