Package: org.grails.web.json

## [Java] Class JSONObject

- org.grails.web.json.JSONObject

- All Implemented Interfaces and Traits:
    JSONElement, java.util.Map

      @java.lang.SuppressWarnings({ "unchecked", "rawtypes" })
      public class JSONObject
      extends java.lang.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`, or `String`. 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.
  Authors:
    JSON.org
  Version:
    2

- - ### Constructor Summary

    Constructors
    Constructor and description
    `JSONObject ()` Construct an empty JSONObject.
    `JSONObject (JSONObject jo, java.lang.String[] sa)` Construct a JSONObject from a subset of another JSONObject.
    `JSONObject (JSONTokener x)` Construct a JSONObject from a JSONTokener.
    `JSONObject (java.util.Map map)` Construct a JSONObject from a Map.
    `JSONObject (java.lang.String string)` Construct a JSONObject from a string.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `JSONObject` | `accumulate(java.lang.String key, java.lang.Object value)` Accumulate values under a key.
    `` | `void` | `clear()`
    `` | `static java.lang.String` | `collectionToString(java.util.Collection c)`
    `` | `boolean` | `containsKey(java.lang.Object o)`
    `` | `boolean` | `containsValue(java.lang.Object o)`
    `` | `static java.lang.String` | `dateToString(java.util.Date d)`
    `` | `protected static void` | `encodeToWriter(java.lang.CharSequence str, java.io.Writer writer)`
    `` | `java.util.Set` | `entrySet()`
    `` | `boolean` | `equals(java.lang.Object o)`
    `` | `java.lang.Object` | `get(java.lang.String key)` Get the value object associated with a key.
    `` | `java.lang.Object` | `get(java.lang.Object o)`
    `` | `boolean` | `getBoolean(java.lang.String key)` Get the boolean value associated with a key.
    `` | `double` | `getDouble(java.lang.String key)` Get the double value associated with a key.
    `` | `int` | `getInt(java.lang.String key)` Get the int value associated with a key.
    `` | `JSONArray` | `getJSONArray(java.lang.String key)` Get the JSONArray value associated with a key.
    `` | `JSONObject` | `getJSONObject(java.lang.String key)` Get the JSONObject value associated with a key.
    `` | `long` | `getLong(java.lang.String key)` Get the long value associated with a key.
    `` | `java.lang.String` | `getString(java.lang.String key)` Get the string associated with a key.
    `` | `boolean` | `has(java.lang.String key)` Determine if the JSONObject contains a specific key.
    `` | `int` | `hashCode()`
    `` | `boolean` | `isEmpty()`
    `` | `boolean` | `isNull(java.lang.String key)` Determine if the value associated with the key is null or if there is no value.
    `` | `java.util.Set` | `keySet()`
    `` | `java.util.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.
    `` | `static java.lang.String` | `numberToString(java.lang.Number n)` Produce a string from a number.
    `` | `java.lang.Object` | `opt(java.lang.String key)` Get an optional value associated with a key.
    `` | `boolean` | `optBoolean(java.lang.String key)` Get an optional boolean associated with a key.
    `` | `boolean` | `optBoolean(java.lang.String key, boolean defaultValue)` Get an optional boolean associated with a key.
    `` | `double` | `optDouble(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.
    `` | `double` | `optDouble(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.
    `` | `int` | `optInt(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.
    `` | `int` | `optInt(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.
    `` | `JSONArray` | `optJSONArray(java.lang.String key)` Get an optional JSONArray associated with a key.
    `` | `JSONObject` | `optJSONObject(java.lang.String key)` Get an optional JSONObject associated with a key.
    `` | `long` | `optLong(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.
    `` | `long` | `optLong(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.
    `` | `java.lang.String` | `optString(java.lang.String key)` Get an optional string associated with a key.
    `` | `java.lang.String` | `optString(java.lang.String key, java.lang.String defaultValue)` Get an optional string associated with a key.
    `` | `JSONObject` | `put(java.lang.String key, boolean value)` Put a key/boolean pair in the JSONObject.
    `` | `JSONObject` | `put(java.lang.String key, double value)` Put a key/double pair in the JSONObject.
    `` | `JSONObject` | `put(java.lang.String key, int value)` Put a key/int pair in the JSONObject.
    `` | `JSONObject` | `put(java.lang.String key, long value)` Put a key/long pair in the JSONObject.
    `` | `JSONObject` | `put(java.lang.String key, java.lang.Object value)` Put a key/value pair in the JSONObject.
    `` | `java.lang.Object` | `put(java.lang.Object o, java.lang.Object o1)`
    `` | `void` | `putAll(java.util.Map map)`
    `` | `JSONObject` | `putOpt(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.
    `` | `static java.lang.String` | `quote(java.lang.String string)` Produce a string in double quotes with backslash sequences in all the right places.
    `` | `java.lang.Object` | `remove(java.lang.String key)` Remove a name and its value, if present.
    `` | `java.lang.Object` | `remove(java.lang.Object o)`
    `` | `int` | `size()`
    `` | `JSONArray` | `toJSONArray(JSONArray names)` Produce a JSONArray containing the values of the members of this JSONObject.
    `` | `java.lang.String` | `toString()` Make an JSON text of this JSONObject.
    `` | `java.lang.String` | `toString(int indentFactor)` Make a prettyprinted JSON text of this JSONObject.
    `` | `java.util.Collection` | `values()`
    `` | `java.io.Writer` | `write(java.io.Writer writer)` Write the contents of the JSONObject as JSON text to a writer.
    `` | `java.io.Writer` | `writeTo(java.io.Writer out)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Constructor Detail

    - #### public JSONObject()

      Construct an empty JSONObject.

    - #### public JSONObject(JSONObject jo, java.lang.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.

      throws:
        JSONException If a value is a non-finite number.
      Parameters:
        `jo` - A JSONObject.
        `sa` - An array of strings.

    - #### public JSONObject(JSONTokener x)

      Construct a JSONObject from a JSONTokener.

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

    - #### public JSONObject(java.util.Map map)

      Construct a JSONObject from a Map.

      Parameters:
        `map` - A map object that can be used to initialize the contents of the JSONObject.

    - #### public JSONObject(java.lang.String string)

      Construct a JSONObject from a string. This is the most commonly used JSONObject constructor.

      throws:
        JSONException If there is a syntax error in the source string.
      Parameters:
        `string` - A string beginning with `{` (left brace) and ending with `}` (right brace).

  - ### Method Detail

    - #### public JSONObject accumulate(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.

      throws:
        JSONException If the value is an invalid number or if the key is null.
      Parameters:
        `key` - A key string.
        `value` - An object to be accumulated under the key.
      Returns:
        this

    - #### public void clear()

    - #### public static java.lang.String collectionToString(java.util.Collection c)

    - #### public boolean containsKey(java.lang.Object o)

    - #### public boolean containsValue(java.lang.Object o)

    - #### public static java.lang.String dateToString(java.util.Date d)

    - #### protected static void encodeToWriter(java.lang.CharSequence str, java.io.Writer writer)

    - #### public java.util.Set entrySet()

    - #### @java.lang.Override public boolean equals(java.lang.Object o)

    - #### public java.lang.Object get(java.lang.String key)

      Get the value object associated with a key.

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

    - #### public java.lang.Object get(java.lang.Object o)

    - #### public boolean getBoolean(java.lang.String key)

      Get the boolean value associated with a key.

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

    - #### public double getDouble(java.lang.String key)

      Get the double value associated with a key.

      throws:
        JSONException if the key is not found or if the value is not a Number object and cannot be converted to a number.
      Parameters:
        `key` - A key string.
      Returns:
        The numeric value.

    - #### public int getInt(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.

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

    - #### public JSONArray getJSONArray(java.lang.String key)

      Get the JSONArray value associated with a key.

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

    - #### public JSONObject getJSONObject(java.lang.String key)

      Get the JSONObject value associated with a key.

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

    - #### public long getLong(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.

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

    - #### public java.lang.String getString(java.lang.String key)

      Get the string associated with a key.

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

    - #### public boolean has(java.lang.String key)

      Determine if the JSONObject contains a specific key.

      Parameters:
        `key` - A key string.
      Returns:
        true if the key exists in the JSONObject.

    - #### @java.lang.Override public int hashCode()

    - #### public boolean isEmpty()

    - #### public boolean isNull(java.lang.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.

    - #### public java.util.Set keySet()

    - #### public java.util.Iterator keys()

      Get an enumeration of the keys of the JSONObject.

      Returns:
        An iterator of the keys.

    - #### public int length()

      Get the number of keys stored in the JSONObject.

      Returns:
        The number of keys in the JSONObject.

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

    - #### public static java.lang.String numberToString(java.lang.Number n)

      Produce a string from a number.

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

    - #### public java.lang.Object opt(java.lang.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.

    - #### public boolean optBoolean(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".

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

    - #### public boolean optBoolean(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).

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

    - #### public double optDouble(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.

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

    - #### public double optDouble(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.

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

    - #### public int optInt(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.

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

    - #### public int optInt(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.

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

    - #### public JSONArray optJSONArray(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.

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

    - #### public JSONObject optJSONObject(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.

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

    - #### public long optLong(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.

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

    - #### public long optLong(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.

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

    - #### public java.lang.String optString(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.

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

    - #### public java.lang.String optString(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.

      Parameters:
        `key` - A key string.
        `defaultValue` - The default.
      Returns:
        A string which is the value.

    - #### public JSONObject put(java.lang.String key, boolean value)

      Put a key/boolean pair in the JSONObject.

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

    - #### public JSONObject put(java.lang.String key, double value)

      Put a key/double pair in the JSONObject.

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

    - #### public JSONObject put(java.lang.String key, int value)

      Put a key/int pair in the JSONObject.

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

    - #### public JSONObject put(java.lang.String key, long value)

      Put a key/long pair in the JSONObject.

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

    - #### public JSONObject put(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.

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

    - #### public java.lang.Object put(java.lang.Object o, java.lang.Object o1)

    - #### public void putAll(java.util.Map map)

    - #### public JSONObject putOpt(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.

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

    - #### public static java.lang.String quote(java.lang.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.

    - #### public java.lang.Object remove(java.lang.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.

    - #### public java.lang.Object remove(java.lang.Object o)

    - #### public int size()

    - #### public JSONArray toJSONArray(JSONArray names)

      Produce a JSONArray containing the values of the members of this JSONObject.

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

    - #### @java.lang.Override public java.lang.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.
      Returns:
        a printable, displayable, portable, transmittable representation of the object, beginning with `{` (left brace) and ending with `}` (right brace).

    - #### public java.lang.String toString(int indentFactor)

      Make a prettyprinted JSON text of this JSONObject.

      Warning: This method assumes that the data structure is acyclical.
      throws:
        JSONException If the object contains an invalid number.
      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).

    - #### public java.util.Collection values()

    - #### public java.io.Writer write(java.io.Writer writer)

      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.
      throws:
        JSONException
      Returns:
        The writer.

    - #### @java.lang.Override public java.io.Writer writeTo(java.io.Writer out)