org.apache.wink.json4j
Class JSONObject

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap
          org.apache.wink.json4j.JSONObject

All Implemented Interfaces:

Serializable, Cloneable, Map, JSONArtifact

Direct Known Subclasses:

OrderedJSONObject

public class JSONObject
extends HashMap
implements JSONArtifact

Models a JSON Object. Extension of HashMap that only allows String keys, and values which are JSON-able (such as a Java Bean).

JSON-able values are: null, and instances of String, Boolean, Number, JSONObject and JSONArray.

Instances of this class are not thread-safe.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Field Summary

static Object

NULL A constant definition reference to Java null.

Constructor Summary

JSONObject()
Create a new instance of this class.

JSONObject(InputStream is)
Create a new instance of this class from the data provided from the input stream.

JSONObject(InputStream is, boolean strict)
Create a new instance of this class from the data provided from the input stream.

JSONObject(JSONObject obj, String[] keys)
Create a new instance of this class taking selected values from the underlying one.

JSONObject(Map map)
Create a new instance of this class using the contents of the provided map.

JSONObject(Map map, boolean includeSuperclass)
Create a new instance of this class using the contents of the provided map.

JSONObject(Object javaBean)
Create a new instance of this class using the properties of the provided JavaBean.

JSONObject(Object javaBean, boolean includeSuperclass)
Create a new instance of this class using the properties of the provided JavaBean.

JSONObject(Reader rdr)
Create a new instance of this class from the data provided from the reader.

JSONObject(Reader rdr, boolean strict)
Create a new instance of this class from the data provided from the reader.

JSONObject(String str)
Create a new instance of this class from the provided JSON object string.

JSONObject(String str, boolean strict)
Create a new instance of this class from the provided JSON object string.

Method Summary

JSONObject	append(String key, Object value) Method to append the 'value' object to the element at entry 'key'.
Object	get(String key) Method to obtain the object value for a key.
boolean	getBoolean(String key) Utility method to obtain the specified key as a 'boolean' value Only boolean true, false, and the String true and false will return.
double	getDouble(String key) Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double, all other types will generate an exception Provided for compatibility to other JSON models.
int	getInt(String key) Utility method to obtain the specified key as a 'int' value Only values of Number will be converted to integer, all other types will generate an exception.
JSONArray	getJSONArray(String key) Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned.
JSONObject	getJSONObject(String key) Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned.
long	getLong(String key) Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long, all other types will generate an exception.
static String[]	getNames(JSONObject obj) Utility function that returns a String[] of all the names of the keys (attributes) of this JSONObject
short	getShort(String key) Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short, all other types will generate an exception.
String	getString(String key) Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned.
boolean	has(String key) Method to test if a key exists in the JSONObject.
boolean	isNull(String key) Method to test if a key is mapped to null.
static boolean	isValidObject(Object object) Return whether the object is a valid value for a property.
static boolean	isValidType(Class clazz) Return whether the class is a valid type of value for a property.
Iterator	keys() Utility function that returns an iterator of all the keys (attributes) of this JSONObject
int	length() Method to return the number of keys in this JSONObject.
JSONArray	names() Utility function that returns a JSONArray of all the names of the keys (attributes) of this JSONObject
Object	opt(String key) Method to obtain the object value for a key.
boolean	optBoolean(String key) Utility method to obtain the specified key as a 'boolean' value Only returns true if the value is boolean true or the string 'true'.
boolean	optBoolean(String key, boolean defaultValue) Utility method to obtain the specified key as a 'boolean' value Only returns true if the value is boolean true or the string 'true'.
double	optDouble(String key) Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double.
double	optDouble(String key, double defaultValue) Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double.
int	optInt(String key) Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models.
int	optInt(String key, int defaultValue) Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models.
JSONArray	optJSONArray(String key) Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned.
JSONArray	optJSONArray(String key, JSONArray defaultValue) Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned.
JSONObject	optJSONObject(String key) Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned.
JSONObject	optJSONObject(String key, JSONObject defaultValue) Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned.
long	optLong(String key) Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long.
long	optLong(String key, long defaultValue) Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long.
short	optShort(String key) Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short.
short	optShort(String key, short defaultValue) Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short.
String	optString(String key) Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned.
String	optString(String key, String defaultValue) Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned.
Object	put(Object key, Object value) (non-Javadoc)
Object	put(Object key, Object value, boolean includeSuperclass) (non-Javadoc)
JSONObject	put(String key, boolean value) Method to add an atomic boolean to the JSONObject.
JSONObject	put(String key, Collection value) Method to add a Collection as a new JSONArray contained in this JSONObject
JSONObject	put(String key, Collection value, boolean includeSuperclass) Method to add a Collection as a new JSONArray contained in this JSONObject
JSONObject	put(String key, double value) Method to add an atomic double to the JSONObject.
JSONObject	put(String key, int value) Method to add an atomic integer to the JSONObject.
JSONObject	put(String key, long value) Method to add an atomic long to the JSONObject.
JSONObject	put(String key, Map value) Method to add a Map as a new JSONObject contained in this JSONObject Same as calling put(String, Map, true);
JSONObject	put(String key, Map value, boolean includeSuperclass) Method to add a Map as a new JSONObject contained in this JSONObject
JSONObject	put(String key, Object value) Similar to default HashMap put, except it returns JSONObject instead of Object.
JSONObject	put(String key, Object[] value) Method to add an Object array as a new JSONArray contained in this JSONObject
JSONObject	put(String key, Object[] value, boolean includeSuperclass) Method to add an Object array as a new JSONArray contained in this JSONObject
JSONObject	put(String key, short value) Method to add an atomic short to the JSONObject.
JSONObject	putOnce(String key, Object value) Put a key/value pair into the JSONObject, but only if key/value are both not null, and only if the key is not present already.
JSONObject	putOpt(String key, Object value) Put a key/value pair into the JSONObject, but only if the key and value are non-null.
Iterator	sortedKeys() Utility function that returns an iterator of all the keys (attributes) of this JSONObject sorted in lexicographic manner (String.compareTo).
JSONArray	toJSONArray(JSONArray names) Produce a JSONArray containing the values of the members of this JSONObject
String	toString() Over-ridden toString() method.
String	toString(boolean verbose) Verbose capable toString method.
String	toString(int indentDepth) Function to return a string of JSON text with specified indention.
String	write() Convert this object into a String of JSON text.
String	write(boolean verbose) Convert this object into a String of JSON text, specifying whether to use verbose (tab-indented) output or not.
String	write(int indentDepth) Convert this object into a String of JSON text, specifying how many spaces should be used for each indent.
OutputStream	write(OutputStream os) Write this object to the stream as JSON text in UTF-8 encoding.
OutputStream	write(OutputStream os, boolean verbose) Convert this object into a stream of JSON text.
OutputStream	write(OutputStream os, int indentDepth) Write this object to the stream as JSON text in UTF-8 encoding, specifying how many spaces should be used for each indent.
Writer	write(Writer writer) Write this object to the writer as JSON text.
Writer	write(Writer writer, boolean verbose) Write this object to the writer as JSON text in UTF-8 encoding, specifying whether to use verbose (tab-indented) output or not.
Writer	write(Writer writer, int indentDepth) Write this object to the writer as JSON text, specifying how many spaces should be used for each indent.

Methods inherited from class java.util.HashMap

clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, putAll, remove, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

NULL

public static final Object NULL

A constant definition reference to Java null. Provided for API compatibility with other JSON parsers.

Constructor Detail

JSONObject

public JSONObject()

Create a new instance of this class.

JSONObject

public JSONObject(JSONObject obj,
                  String[] keys)
           throws JSONException

Create a new instance of this class taking selected values from the underlying one. If a key is not found, then it will be copied into the new JSONObject.

Parameters:

obj - The JSONObject to extract values from.

keys - The keys to take from the JSONObject and apply to this instance.

Throws:

JSONException - Thrown if a key is duplicated in the string[] keys

JSONObject

public JSONObject(String str)
           throws JSONException

Create a new instance of this class from the provided JSON object string. Note: This is the same as new JSONObject(str, false); Parsing in non-strict mode.

Parameters:

str - The JSON string to parse.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(String str,
                  boolean strict)
           throws JSONException

Create a new instance of this class from the provided JSON object string.

Parameters:

str - The JSON string to parse.

strict - Whether or not to parse in 'strict' mode, meaning all strings must be quoted (including identifiers), and comments are not allowed.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(Reader rdr)
           throws JSONException

Create a new instance of this class from the data provided from the reader. The reader content must be a JSON object string. Note: The reader will not be closed, that is left to the caller. Note: This is the same as new JSONObject(rdr, false); Parsing in non-strict mode.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(Reader rdr,
                  boolean strict)
           throws JSONException

Create a new instance of this class from the data provided from the reader. The reader content must be a JSON object string. Note: The reader will not be closed, that is left to the caller.

Parameters:

rdr - The reader from which to read the JSON.

strict - Whether or not to parse in 'strict' mode, meaning all strings must be quoted (including identifiers), and comments are not allowed.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(InputStream is)
           throws JSONException

Create a new instance of this class from the data provided from the input stream. The stream content must be a JSON object string. Note: The input stream content is assumed to be UTF-8 encoded. Note: The InputStream will not be closed, that is left to the caller. Note: This is the same as new JSONObject(is, false); Parsing in non-strict mode.

Parameters:

is - The InputStream from which to read the JSON.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(InputStream is,
                  boolean strict)
           throws JSONException

Create a new instance of this class from the data provided from the input stream. The stream content must be a JSON object string. Note: The input stream content is assumed to be UTF-8 encoded. Note: The InputStream will not be closed, that is left to the caller.

Parameters:

is - The InputStream from which to read the JSON.

strict - Whether or not to parse in 'strict' mode, meaning all strings must be quoted (including identifiers), and comments are not allowed.

Throws:

JSONException - Thrown when the string passed is null, or malformed JSON..

JSONObject

public JSONObject(Map map)

Create a new instance of this class using the contents of the provided map. The contents of the map should be values considered JSONable. It will try to convert JavaBeans in the map to JSONObjects if possible.

Parameters:

map - The map of key/value pairs to insert into this JSON object

JSONObject

public JSONObject(Object javaBean)
           throws JSONException

Create a new instance of this class using the properties of the provided JavaBean. The bean is converted to a JSONObject via reflection of getter methods.

Parameters:

javaBean - A java bean with getters for properties.

Throws:

JSONException - Thrown when contents in the map cannot be made JSONable.

NullPointerException - Thrown if the map is null, or a key in the map is null..

JSONObject

public JSONObject(Object javaBean,
                  boolean includeSuperclass)
           throws JSONException

Create a new instance of this class using the properties of the provided JavaBean. The bean is converted to a JSONObject via reflection of getter methods.

Parameters:

javaBean - A java bean with getters for properties.

includeSuperclass - Boolean indicating that if the object is a JavaBean, include superclass getter properties.

Throws:

JSONException - Thrown when contents in the map cannot be made JSONable.

NullPointerException - Thrown if the map is null, or a key in the map is null..

JSONObject

public JSONObject(Map map,
                  boolean includeSuperclass)
           throws JSONException

Create a new instance of this class using the contents of the provided map. The contents of the map should be values considered JSONable.

Parameters:

map - The map of key/value pairs to insert into this JSON object

includeSuperclass - For values of the map which are JavaBeans, include superclass getter properties.

Throws:

JSONException - Thrown when contents in the map cannot be made JSONable.

NullPointerException - Thrown if the map is null, or a key in the map is null..

Method Detail

isValidObject

public static boolean isValidObject(Object object)

Return whether the object is a valid value for a property.

Parameters:

object - The object to check for validity as a JSON property value.

Returns:

boolean indicating if the provided object is directly convertable to JSON.

isValidType

public static boolean isValidType(Class clazz)

Return whether the class is a valid type of value for a property.

Parameters:

clazz - The class type to check for validity as a JSON object type.

Returns:

boolean indicating if the provided class is directly convertable to JSON.

write

public OutputStream write(OutputStream os)
                   throws JSONException

Write this object to the stream as JSON text in UTF-8 encoding. Same as calling write(os,false); Note that encoding is always written as UTF-8, as per JSON spec.

Specified by:

write in interface JSONArtifact

Parameters:

os - The output stream to write data to.

Returns:

The passed in OutputStream.

Throws:

JSONException - Thrown on IO errors during serialization.

write

public OutputStream write(OutputStream os,
                          boolean verbose)
                   throws JSONException

Convert this object into a stream of JSON text. Same as calling write(writer,false); Note that encoding is always written as UTF-8, as per JSON spec.

Specified by:

write in interface JSONArtifact

Parameters:

os - The output stream to write data to.

verbose - Whether or not to write the JSON text in a verbose format.

Returns:

The passed in OutputStream.

Throws:

JSONException - Thrown on IO errors during serialization.

write

public OutputStream write(OutputStream os,
                          int indentDepth)
                   throws JSONException

Write this object to the stream as JSON text in UTF-8 encoding, specifying how many spaces should be used for each indent.

Specified by:

write in interface JSONArtifact

Parameters:

indentDepth - How many spaces to use for each indent level. Should be one to eight. Less than one means no intending, greater than 8 and it will just use tab.

Returns:

The passed in OutputStream.

Throws:

JSONException - Thrown on IO errors during serialization.

write

public Writer write(Writer writer)
             throws JSONException

Write this object to the writer as JSON text. Same as calling write(writer,false);

Specified by:

write in interface JSONArtifact

Parameters:

writer - The writer which to write the JSON text to.

Returns:

The passed in writer.

Throws:

JSONException - Thrown on IO errors during serialization.

write

public Writer write(Writer writer,
                    boolean verbose)
             throws JSONException

Write this object to the writer as JSON text in UTF-8 encoding, specifying whether to use verbose (tab-indented) output or not.

Specified by:

write in interface JSONArtifact

Parameters:

writer - The writer which to write the JSON text to.

Returns:

The passed in writer.

Throws:

JSONException - Thrown on IO errors during serialization.

write

public Writer write(Writer writer,
                    int indentDepth)
             throws JSONException

Write this object to the writer as JSON text, specifying how many spaces should be used for each indent. This is an alternate indent style to using tabs.

Specified by:

write in interface JSONArtifact

Parameters:

writer - The writer which to write the JSON text to.

indentDepth - How many spaces to use for each indent. The value should be between one to eight.

Returns:

The passed in writer.

Throws:

JSONException - Thrown on errors during serialization.

write

public String write(int indentDepth)
             throws JSONException

Convert this object into a String of JSON text, specifying how many spaces should be used for each indent. This is an alternate indent style to using tabs.

Specified by:

write in interface JSONArtifact

Parameters:

indentDepth - How many spaces to use for each indent. The value should be between one to eight. Less than one means no indenting, greater than 8 and it will just use tab.

Throws:

JSONException - Thrown on errors during serialization.

write

public String write(boolean verbose)
             throws JSONException

Convert this object into a String of JSON text, specifying whether to use verbose (tab-indented) output or not.

Specified by:

write in interface JSONArtifact

Parameters:

verbose - Whether or not to write in compressed format.

Throws:

JSONException - Thrown on errors during serialization.

write

public String write()
             throws JSONException

Convert this object into a String of JSON text. Same as write(false);

Specified by:

write in interface JSONArtifact

Throws:

JSONException - Thrown on IO errors during serialization.

get

public Object get(String key)
           throws JSONException

Method to obtain the object value for a key. This string-based method is provided for API compatibility to other JSON models.

Parameters:

key - The key (attribute) name to obtain the value for.

Throws:

JSONException - Thrown if the noted key is not in the map of key/value pairs.

opt

public Object opt(String key)

Method to obtain the object value for a key. If the key is not in the map, null is returned. This string-based method is provided for API compatibility to other JSON models.

Parameters:

key - The key (attribute) name to obtain the value for.

put

public Object put(Object key,
                  Object value,
                  boolean includeSuperclass)
           throws JSONException

(non-Javadoc)

Parameters:

key - The key to put in the JSONObject

value - The value to put in the JSONObject

includeSuperclass - Boolean indicating that if the object is a JavaBean, include superclass getter properties.

Throws:

JSONException. - Thrown if key is null, not a string, or the value could not be converted.

JSONException

See Also:

HashMap.put(java.lang.Object, java.lang.Object)

put

public Object put(Object key,
                  Object value)

(non-Javadoc)

Specified by:

put in interface Map

Overrides:

put in class HashMap

See Also:

This is the same as calling put(key, value, true);

put

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

Similar to default HashMap put, except it returns JSONObject instead of Object.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null, not a string, or the value could not be converted to JSON.

JSONException

See Also:

HashMap.put(java.lang.Object, java.lang.Object)

put

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

Method to add an atomic boolean to the JSONObject. param key The key/attribute name to set the boolean at.

Parameters:

value - The boolean value.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null or not a string.

JSONException

put

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

Method to add an atomic double to the JSONObject. param key The key/attribute name to set the double at.

Parameters:

value - The double value.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null or not a string.

JSONException

put

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

Method to add an atomic integer to the JSONObject. param key The key/attribute name to set the integer at.

Parameters:

value - The integer value.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null or not a string.

JSONException

put

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

Method to add an atomic short to the JSONObject. param key The key/attribute name to set the integer at.

Parameters:

value - The integer value.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null or not a string.

JSONException

put

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

Method to add an atomic long to the JSONObject.

Parameters:

key - The key/attribute name to set the long to.

value - The long value.

Returns:

A reference to this object instance.

Throws:

JSONException. - Thrown if key is null or not a string.

JSONException

put

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

Method to add a Map as a new JSONObject contained in this JSONObject

Parameters:

key - The key/attribute name to set the new JSONObject to.

value - The Map object to convert to a JSONObject and store.

includeSuperclass - For values of the map which are JavaBeans and are converted, include superclass getter properties.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the map cannot be converted to something JSONable.

put

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

Method to add a Map as a new JSONObject contained in this JSONObject Same as calling put(String, Map, true);

Parameters:

key - The key/attribute name to set the new JSONObject to.

value - The Map object to convert to a JSONObject and store.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the map cannot be converted to something JSONable.

put

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

Method to add a Collection as a new JSONArray contained in this JSONObject

Parameters:

key - The key/attribute name to set the collection to.

value - The Map object to convert to a JSONObject and store.

includeSuperclass - For values of the map which are JavaBeans and are converted, include superclass getter properties.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the Collection cannot be converted to something JSONable.

put

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

Method to add a Collection as a new JSONArray contained in this JSONObject

Parameters:

key - The key/attribute name to set the collection to.

value - The Map object to convert to a JSONObject and store.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the Collection cannot be converted to something JSONable.

put

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

Method to add an Object array as a new JSONArray contained in this JSONObject

Parameters:

key - The key/attribute name to set the collection to.

value - The Object array to convert to a JSONArray and store.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the Collection cannot be converted to something JSONable.

put

public JSONObject put(String key,
                      Object[] value,
                      boolean includeSuperclass)
               throws JSONException

Method to add an Object array as a new JSONArray contained in this JSONObject

Parameters:

key - The key/attribute name to set the collection to.

value - The Object array to convert to a JSONArray and store.

includeSuperclass - For values of the Object array which are JavaBeans and are converted, include superclass getter properties.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown when contents in the Collection cannot be converted to something JSONable.

getBoolean

public boolean getBoolean(String key)
                   throws JSONException

Utility method to obtain the specified key as a 'boolean' value Only boolean true, false, and the String true and false will return. In this case null, the number 0, and empty string should be treated as false. everything else is true. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a boolean instance, or the strings 'true' or 'false'.

Returns:

A boolean value (true or false), if the value stored for key is a Boolean, or the strings 'true' or 'false'.

Throws:

JSONException

optBoolean

public boolean optBoolean(String key)

Utility method to obtain the specified key as a 'boolean' value Only returns true if the value is boolean true or the string 'true'. All other values return false. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A boolean value (true or false), if the value stored for key is a Boolean, or the strings 'true' or 'false'.

optBoolean

public boolean optBoolean(String key,
                          boolean defaultValue)

Utility method to obtain the specified key as a 'boolean' value Only returns true if the value is boolean true or the string 'true'. All other values return false. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default value to return.

Returns:

A boolean value (true or false), if the value stored for key is a Boolean, or the strings 'true' or 'false'.

getDouble

public double getDouble(String key)
                 throws JSONException

Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double, all other types will generate an exception Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a Double instance, or cannot be converted to a double.

Returns:

A double value if the value stored for key is an instance of Number.

Throws:

JSONException

optDouble

public double optDouble(String key)

Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double. all other values will return Double.NaN. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A double value if the value stored for key is an instance of Number.

optDouble

public double optDouble(String key,
                        double defaultValue)

Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double. all other values will return Double.NaN. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default double value to return in case of NaN/null values in map.

Returns:

A double value if the value stored for key is an instance of Number.

getShort

public short getShort(String key)
               throws JSONException

Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short, all other types will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a Short instance, or cannot be converted to a short.

Returns:

A short value if the value stored for key is an instance of Number.

Throws:

JSONException

optShort

public short optShort(String key)

Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short. All other types return 0. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A short value if the value stored for key is an instance of Number. 0 otherwise.

optShort

public short optShort(String key,
                      short defaultValue)

Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default value to return in the case of null/nonNumber values in the map.

Returns:

A short value if the value stored for key is an instance of Number. 0 otherwise.

getInt

public int getInt(String key)
           throws JSONException

Utility method to obtain the specified key as a 'int' value Only values of Number will be converted to integer, all other types will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a Double instance, or cannot be converted to a double.

Returns:

A int value if the value stored for key is an instance of Number.

Throws:

JSONException

optInt

public int optInt(String key)

Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models. Only values of Number will be converted to integer, all other types will return 0.

Parameters:

key - The key to look up.

Returns:

A int value if the value stored for key is an instance of Number. 0 otherwise.

optInt

public int optInt(String key,
                  int defaultValue)

Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models. Only values of Number will be converted to integer

Parameters:

key - The key to look up.

defaultValue - The default int value to return in case of null/non-number values in the map.

Returns:

A int value if the value stored for key is an instance of Number.

getLong

public long getLong(String key)
             throws JSONException

Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long, all other types will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a Long instance, or cannot be converted to a long..

Returns:

A long value if the value stored for key is an instance of Number.

Throws:

JSONException

optLong

public long optLong(String key)
             throws JSONException

Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long. all other types return 0. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A long value if the value stored for key is an instance of Number, 0 otherwise.

Throws:

JSONException

optLong

public long optLong(String key,
                    long defaultValue)
             throws JSONException

Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long. all other types return 0. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default long value to return in case of null/non Number values in the map.

Returns:

A long value if the value stored for key is an instance of Number, defaultValue otherwise.

Throws:

JSONException

getString

public String getString(String key)
                 throws JSONException

Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is null.

Returns:

A string value if the value if the value stored for key is not null.

Throws:

JSONException

optString

public String optString(String key)

Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is null.

Returns:

A string value if the value if the value stored for key is not null.

optString

public String optString(String key,
                        String defaultValue)

Utility method to obtain the specified key as a 'string' value Only values that can be easily converted to string will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default String value to return in the case of null values in the map.

Returns:

A string value if the value if the value stored for key is not null, defaultValue otherwise.

getJSONObject

public JSONObject getJSONObject(String key)
                         throws JSONException

Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a JSONObject instance.

Returns:

A JSONObject value if the value stored for key is an instance or subclass of JSONObject.

Throws:

JSONException

optJSONObject

public JSONObject optJSONObject(String key)

Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A JSONObject value if the value stored for key is an instance or subclass of JSONObject, null otherwise.

optJSONObject

public JSONObject optJSONObject(String key,
                                JSONObject defaultValue)

Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default JSONObject to return in the case of null/non JSONObject values in the map.

Returns:

A JSONObject value if the value stored for key is an instance or subclass of JSONObject, defaultValue otherwise.

getJSONArray

public JSONArray getJSONArray(String key)
                       throws JSONException

Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up. throws JSONException Thrown when the type returned by get(key) is not a Long instance, or cannot be converted to a long..

Returns:

A JSONArray value if the value stored for key is an instance or subclass of JSONArray.

Throws:

JSONException

optJSONArray

public JSONArray optJSONArray(String key)
                       throws JSONException

Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

Returns:

A JSONArray value if the value stored for key is an instance or subclass of JSONArray, null otherwise.

Throws:

JSONException

optJSONArray

public JSONArray optJSONArray(String key,
                              JSONArray defaultValue)
                       throws JSONException

Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned. A null will generate an exception. Provided for compatibility to other JSON models.

Parameters:

key - The key to look up.

defaultValue - The default value to return if the value in the map is null/not a JSONArray.

Returns:

A JSONArray value if the value stored for key is an instance or subclass of JSONArray, defaultValue otherwise.

Throws:

JSONException

putOnce

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

Put a key/value pair into the JSONObject, but only if key/value are both not null, and only if the key is not present already. Provided for compatibility to existing models.

Parameters:

key - The ket to place in the array

value - The value to place in the array

Returns:

Reference to the current JSONObject.

Throws:

JSONException - - Thrown if the key already exists or if key or value is null

putOpt

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

Put a key/value pair into the JSONObject, but only if the key and value are non-null.

Parameters:

key - The keey (attribute) name to assign to the value.

value - The value to put into the JSONObject.

Returns:

Reference to the current JSONObject.

Throws:

JSONException - - if the value is a non-finite number

length

public int length()

Method to return the number of keys in this JSONObject. This function merely maps to HashMap.size(). Provided for API compatibility.

Returns:

returns the number of keys in the JSONObject.

append

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

Method to append the 'value' object to the element at entry 'key'. If JSONObject.has(key) returns false, a new array is created and the value is appended to it. If the object as position key is not an array, then a new JSONArray is created and both current and new values are appended to it, then the value of the attribute is set to the new array. If the current value is already an array, then 'value' is added to it.

Parameters:

key - The key/attribute name to append to.

value - The value to append to it.

Returns:

A reference to this object instance.

Throws:

JSONException - Thrown if the value to append is not JSONAble.

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 the a list of key strings. This determines the sequence of values in the result.

Returns:

A JSONArray of the values found for the names provided.

Throws:

JSONException - - if errors occur during storing the values in a JSONArray

has

public boolean has(String key)

Method to test if a key exists in the JSONObject.

Parameters:

key - The key to test.

Returns:

true if the key is defined in the JSONObject (regardless of value), or false if the key is not in the JSONObject

isNull

public boolean isNull(String key)

Method to test if a key is mapped to null. This method will also return true if the key has not been put in the JSONObject yet.

Parameters:

key - The key to test for null.

Returns:

true if the key is not in the map or if the value referenced by the key is null.

keys

public Iterator keys()

Utility function that returns an iterator of all the keys (attributes) of this JSONObject

Returns:

An iterator of all keys in the object.

names

public JSONArray names()

Utility function that returns a JSONArray of all the names of the keys (attributes) of this JSONObject

Returns:

All the keys in the JSONObject as a JSONArray.

getNames

public static String[] getNames(JSONObject obj)

Utility function that returns a String[] of all the names of the keys (attributes) of this JSONObject

Returns:

All the keys in the JSONObject as a String[].

sortedKeys

public Iterator sortedKeys()

Utility function that returns an iterator of all the keys (attributes) of this JSONObject sorted in lexicographic manner (String.compareTo).

Returns:

An iterator of all keys in the object in lexicographic (character code) sorted order.

toString

public String toString()

Over-ridden toString() method. Returns the same value as write(), which is a compact JSON String. If an error occurs in the serialization, the return will be of format: JSON Generation Error: []

Overrides:

toString in class AbstractMap

Returns:

A string of JSON text, if possible.

toString

public String toString(boolean verbose)

Verbose capable toString method. If an error occurs in the serialization, the return will be of format: JSON Generation Error: []

Parameters:

verbose - Whether or not to tab-indent the output.

Returns:

A string of JSON text, if possible.

toString

public String toString(int indentDepth)
                throws JSONException

Function to return a string of JSON text with specified indention. Returns the same value as write(indentDepth). If an error occurs in the serialization, a JSONException is thrown.

Returns:

A string of JSON text, if possible.

Throws:

JSONException