Home » tapestry-src-5.0.19 » org.apache.tapestry5.json » [javadoc | source]
public final class: JSONObject [javadoc | source]
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:

This class, and the other related classes, have been heavily modified from the original source, to fit Tapestry standards and to make use of JDK 1.5 features such as generics. Further, since the interest of Tapestry is primarily constructing JSON (and not parsing it), many of the non-essential methods have been removed (since the original code came with no tests).

Field Summary
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"
 public JSONObject() 
 JSONObject(JSONTokener x) 
    Construct a JSONObject from a JSONTokener.
    x - A JSONTokener object containing the source string. @ If there is a syntax error in the source string.
 public JSONObject(String string) 
    Construct a JSONObject from a string. This is the most commonly used JSONObject constructor.
    string - A string beginning with { (left brace) and ending with } (right brace).
    RuntimeException - If there is a syntax error in the source string.
 public JSONObject(JSONObject source,
    String propertyNames) 
    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.
    source - A JSONObject.
    propertyNames - The strings to copy.
    RuntimeException - If a value is a non-finite number.
Method from org.apache.tapestry5.json.JSONObject Summary:
accumulate,   append,   doubleToString,   equals,   get,   getBoolean,   getDouble,   getInt,   getJSONArray,   getJSONObject,   getLong,   getString,   has,   isNull,   keys,   length,   names,   numberToString,   opt,   put,   quote,   remove,   testValidity,   toString,   valueToString
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.tapestry5.json.JSONObject Detail:
 public JSONObject accumulate(String key,
    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.
 public JSONObject append(String key,
    Object value) 
    Append values to the array under a key. If the key does not exist in the JSONObject, then the key is put in the JSONObject with its value being a JSONArray containing the value parameter. If the key was already associated with a JSONArray, then the value parameter is appended to it.
 static String doubleToString(double d) 
    Produce a string from a double. The string "null" will be returned if the number is not finite.
 public boolean equals(Object obj) 
    Returns true if the other object is a JSONObject and its set of properties matches this object's properties.


 public Object get(String key) 
    Get the value object associated with a key.
 public boolean getBoolean(String key) 
    Get the boolean value associated with a key.
 public double getDouble(String key) 
    Get the double value associated with a key.
 public int getInt(String key) 
    Get the int value associated with a key. If the number value is too large for an int, it will be clipped.
 public JSONArray getJSONArray(String key) 
    Get the JSONArray value associated with a key.
 public JSONObject getJSONObject(String key) 
    Get the JSONObject value associated with a key.
 public long getLong(String key) 
    Get the long value associated with a key. If the number value is too long for a long, it will be clipped.
 public String getString(String key) 
    Get the string associated with a key.
 public boolean has(String key) 
    Determine if the JSONObject contains a specific key.
 public boolean isNull(String key) 
    Determine if the value associated with the key is null or if there is no value.
 public Set<String> keys() 
    Get an enumeration of the keys of the JSONObject. Caution: the set should not be modified.
 public int length() 
    Get the number of keys stored in the JSONObject.
 public 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.
 public Object opt(String key) 
    Get an optional value associated with a key.
 public JSONObject put(String key,
    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.
 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
 public Object remove(String key) 
    Remove a name and its value, if present.
 static  void testValidity(Object value) 
    Throw an exception if the object is an NaN or infinite number, or not a type which may be stored.
 public String toString() 
    Make a 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.

 static String valueToString(Object value) 
    Make a JSON text of an Object value. If the object has an value.toJSONString() method, then that method will be used to produce the JSON text. The method is required to produce a strictly conforming text. If the object does not contain a toJSONString method (which is the most common case), then a text will be produced by the rules.

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