org.apache.wink.json4j
Class JSONObject

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.HashMap
          extended by org.apache.wink.json4j.JSONObject
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.Map, JSONArtifact
Direct Known Subclasses:
OrderedJSONObject

public class JSONObject
extends java.util.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
java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>
 
Field Summary
static java.lang.Object NULL
          A constant definition reference to Java null.
 
Constructor Summary
JSONObject()
          Create a new instance of this class.
JSONObject(java.io.InputStream is)
          Create a new instance of this class from the data provided from the input stream.
JSONObject(java.io.InputStream is, boolean strict)
          Create a new instance of this class from the data provided from the input stream.
JSONObject(JSONObject obj, java.lang.String[] keys)
          Create a new instance of this class taking selected values from the underlying one.
JSONObject(java.util.Map map)
          Create a new instance of this class using the contents of the provided map.
JSONObject(java.util.Map map, boolean includeSuperclass)
          Create a new instance of this class using the contents of the provided map.
JSONObject(java.lang.Object javaBean)
          Create a new instance of this class using the properties of the provided JavaBean.
JSONObject(java.lang.Object javaBean, boolean includeSuperclass)
          Create a new instance of this class using the properties of the provided JavaBean.
JSONObject(java.io.Reader rdr)
          Create a new instance of this class from the data provided from the reader.
JSONObject(java.io.Reader rdr, boolean strict)
          Create a new instance of this class from the data provided from the reader.
JSONObject(java.lang.String str)
          Create a new instance of this class from the provided JSON object string.
JSONObject(java.lang.String str, boolean strict)
          Create a new instance of this class from the provided JSON object string.
 
Method Summary
 JSONObject append(java.lang.String key, java.lang.Object value)
          Method to append the 'value' object to the element at entry 'key'.
 java.lang.Object get(java.lang.String key)
          Method to obtain the object value for a key.
 boolean getBoolean(java.lang.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(java.lang.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(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned.
 JSONObject getJSONObject(java.lang.String key)
          Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned.
 long getLong(java.lang.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 java.lang.String[] getNames(JSONObject obj)
          Utility function that returns a String[] of all the names of the keys (attributes) of this JSONObject
 short getShort(java.lang.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.
 java.lang.String getString(java.lang.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(java.lang.String key)
          Method to test if a key exists in the JSONObject.
 boolean isNull(java.lang.String key)
          Method to test if a key is mapped to null.
static boolean isValidObject(java.lang.Object object)
          Return whether the object is a valid value for a property.
static boolean isValidType(java.lang.Class clazz)
          Return whether the class is a valid type of value for a property.
 java.util.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
 java.lang.Object opt(java.lang.String key)
          Method to obtain the object value for a key.
 boolean optBoolean(java.lang.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(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a 'double' value Only values of Number will be converted to double.
 double optDouble(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models.
 int optInt(java.lang.String key, int defaultValue)
          Utility method to obtain the specified key as a 'int' value Provided for compatibility to other JSON models.
 JSONArray optJSONArray(java.lang.String key)
          Utility method to obtain the specified key as a JSONArray Only values that are instances of JSONArray will be returned.
 JSONArray optJSONArray(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a JSONObject Only values that are instances of JSONObject will be returned.
 JSONObject optJSONObject(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a 'long' value Only values of Number will be converted to long.
 long optLong(java.lang.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(java.lang.String key)
          Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short.
 short optShort(java.lang.String key, short defaultValue)
          Utility method to obtain the specified key as a 'short' value Only values of Number will be converted to short.
 java.lang.String optString(java.lang.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.
 java.lang.String optString(java.lang.String key, java.lang.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.
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          (non-Javadoc)
 java.lang.Object put(java.lang.Object key, java.lang.Object value, boolean includeSuperclass)
          (non-Javadoc)
 JSONObject put(java.lang.String key, boolean value)
          Method to add an atomic boolean to the JSONObject.
 JSONObject put(java.lang.String key, java.util.Collection value)
          Method to add a Collection as a new JSONArray contained in this JSONObject
 JSONObject put(java.lang.String key, java.util.Collection value, boolean includeSuperclass)
          Method to add a Collection as a new JSONArray contained in this JSONObject
 JSONObject put(java.lang.String key, double value)
          Method to add an atomic double to the JSONObject.
 JSONObject put(java.lang.String key, int value)
          Method to add an atomic integer to the JSONObject.
 JSONObject put(java.lang.String key, long value)
          Method to add an atomic long to the JSONObject.
 JSONObject put(java.lang.String key, java.util.Map value)
          Method to add a Map as a new JSONObject contained in this JSONObject Same as calling put(String, Map, true);
 JSONObject put(java.lang.String key, java.util.Map value, boolean includeSuperclass)
          Method to add a Map as a new JSONObject contained in this JSONObject
 JSONObject put(java.lang.String key, java.lang.Object value)
          Similar to default HashMap put, except it returns JSONObject instead of Object.
 JSONObject put(java.lang.String key, java.lang.Object[] value)
          Method to add an Object array as a new JSONArray contained in this JSONObject
 JSONObject put(java.lang.String key, java.lang.Object[] value, boolean includeSuperclass)
          Method to add an Object array as a new JSONArray contained in this JSONObject
 JSONObject put(java.lang.String key, short value)
          Method to add an atomic short to the JSONObject.
 JSONObject putOnce(java.lang.String key, java.lang.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(java.lang.String key, java.lang.Object value)
          Put a key/value pair into the JSONObject, but only if the key and value are non-null.
 java.util.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
 java.lang.String toString()
          Over-ridden toString() method.
 java.lang.String toString(boolean verbose)
          Verbose capable toString method.
 java.lang.String toString(int indentDepth)
          Function to return a string of JSON text with specified indention.
 java.lang.String write()
          Convert this object into a String of JSON text.
 java.lang.String write(boolean verbose)
          Convert this object into a String of JSON text, specifying whether to use verbose (tab-indented) output or not.
 java.lang.String write(int indentDepth)
          Convert this object into a String of JSON text, specifying how many spaces should be used for each indent.
 java.io.OutputStream write(java.io.OutputStream os)
          Write this object to the stream as JSON text in UTF-8 encoding.
 java.io.OutputStream write(java.io.OutputStream os, boolean verbose)
          Convert this object into a stream of JSON text.
 java.io.OutputStream write(java.io.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.
 java.io.Writer write(java.io.Writer writer)
          Write this object to the writer as JSON text.
 java.io.Writer write(java.io.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.
 java.io.Writer write(java.io.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 java.lang.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,
                  java.lang.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(java.lang.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(java.lang.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(java.io.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(java.io.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(java.io.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(java.io.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(java.util.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(java.lang.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.
java.lang.NullPointerException - Thrown if the map is null, or a key in the map is null..

JSONObject

public JSONObject(java.lang.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.
java.lang.NullPointerException - Thrown if the map is null, or a key in the map is null..

JSONObject

public JSONObject(java.util.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.
java.lang.NullPointerException - Thrown if the map is null, or a key in the map is null..
Method Detail

isValidObject

public static boolean isValidObject(java.lang.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(java.lang.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 java.io.OutputStream write(java.io.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 java.io.OutputStream write(java.io.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 java.io.OutputStream write(java.io.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 java.io.Writer write(java.io.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 java.io.Writer write(java.io.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 java.io.Writer write(java.io.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Object get(java.lang.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 java.lang.Object opt(java.lang.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 java.lang.Object put(java.lang.Object key,
                            java.lang.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 java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
(non-Javadoc)

Specified by:
put in interface java.util.Map
Overrides:
put in class java.util.HashMap
See Also:
This is the same as calling put(key, value, true);

put

public JSONObject put(java.lang.String key,
                      java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String key,
                      java.util.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(java.lang.String key,
                      java.util.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(java.lang.String key,
                      java.util.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(java.lang.String key,
                      java.util.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(java.lang.String key,
                      java.lang.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(java.lang.String key,
                      java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.lang.String getString(java.lang.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 java.lang.String optString(java.lang.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 java.lang.String optString(java.lang.String key,
                                  java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String key,
                          java.lang.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(java.lang.String key,
                         java.lang.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(java.lang.String key,
                         java.lang.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(java.lang.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(java.lang.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 java.util.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 java.lang.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 java.util.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 java.lang.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 java.util.AbstractMap
Returns:
A string of JSON text, if possible.

toString

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


Copyright © 2009-2013 The Apache Software Foundation. All Rights Reserved.