Groovy Documentation

## org.codehaus.groovy.grails.web.json
[Java] Class JSONObject

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

All Implemented Interfaces:
  JSONElement

    @SuppressWarnings({ "unchecked", "rawtypes" })
    public class JSONObject

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.

Authors:
  JSON.org

Version:
  2

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

Method Summary
`java.lang.Object` | `JSONObject()` Construct an empty JSONObject.
`java.lang.Object` | `JSONObject(JSONObject jo, String[] sa)` Construct a JSONObject from a subset of another JSONObject.
`java.lang.Object` | `JSONObject(JSONTokener x)` Construct a JSONObject from a JSONTokener.
`java.lang.Object` | `JSONObject(java.util.Map map)` Construct a JSONObject from a Map.
`java.lang.Object` | `JSONObject(java.lang.String string)` Construct a JSONObject from a string.
`JSONObject` | `accumulate(java.lang.String key, java.lang.Object value)` Accumulate values under a key.
`void` | `clear()`
`boolean` | `containsKey(java.lang.Object o)`
`boolean` | `containsValue(java.lang.Object o)`
`static java.lang.String` | `dateToString(java.util.Date d)`
`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.

Methods inherited from class java.lang.Object
java.lang.Object#wait(), java.lang.Object#wait(long), java.lang.Object#wait(long, int), 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()

Field Detail

### NULL

    public static final java.lang.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"`.

Method Detail

### JSONObject

    public java.lang.Object JSONObject()

  Construct an empty JSONObject.

### JSONObject

    public java.lang.Object 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.
  throws:
    JSONException If a value is a non-finite number.
  Parameters:
    `jo` - A JSONObject.
    `sa` - An array of strings.

### JSONObject

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

### JSONObject

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

### JSONObject

    public java.lang.Object 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).

### accumulate

    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.

### clear

    public void clear()

### containsKey

    public boolean containsKey(java.lang.Object o)

### containsValue

    public boolean containsValue(java.lang.Object o)

### dateToString

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

### entrySet

    public java.util.Set entrySet()

### equals

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

### get

    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.

### get

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

### getBoolean

    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.

### getDouble

    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.

### getInt

    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.

### getJSONArray

    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.

### getJSONObject

    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.

### getLong

    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.

### getString

    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.

### has

    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.

### hashCode

    @Override
    public int hashCode()

### isEmpty

    public boolean isEmpty()

### isNull

    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.

### keySet

    public java.util.Set keySet()

### keys

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

### opt

    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.

### optBoolean

    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.

### optBoolean

    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.

### optDouble

    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.

### optDouble

    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.

### optInt

    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.

### optInt

    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.

### optJSONArray

    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.

### optJSONObject

    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.

### optLong

    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.

### optLong

    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.

### optString

    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.

### optString

    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.

### put

    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.

### put

    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.

### put

    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.

### put

    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.

### put

    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.

### put

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

### putAll

    public void putAll(java.util.Map map)

### putOpt

    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.

### quote

    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.

### remove

    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.

### remove

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

### size

    public int size()

### toJSONArray

    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.

### toString

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

### toString

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

### values

    public java.util.Collection values()

### write

    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.

Groovy Documentation