org.elkoserver.json
Class JSONObject

java.lang.Object
  org.elkoserver.json.JSONObject

public class JSONObject
extends Object

A parsed JSON object. This class represents a JSON object that has been received or is being constructed. It provides random access to the properties of the object.

Constructor Summary

JSONObject()
Construct a new, empty JSON object.

JSONObject(JSONObject original)
Construct a JSON object by copying another pre-existing JSON object.

JSONObject(Map<String,Object> map)
Construct a JSON object from a pre-existing map.

JSONObject(String type)
Construct a JSON object representing a typed struct.

JSONObject(String target, String verb)
Construct a JSON object representing a message.

Method Summary

void	addProperty(String name, boolean value) Add a boolean property to the object.
void	addProperty(String name, double value) Add a double property to the object.
void	addProperty(String name, Encodable value) Add an object that can be encoded as JSON to an object.
void	addProperty(String name, int value) Add an integer property to the object.
void	addProperty(String name, long value) Add a long property to the object.
void	addProperty(String name, Object value) Add a property to the object.
void	copyProperty(String name, JSONObject orig) Add a property to the object by copying a property of another object.
JSONArray	getArray(String name) Obtain an array property value.
boolean	getBoolean(String name) Obtain the boolean value of a property.
double	getDouble(String name) Obtain a double property value.
int	getInt(String name) Obtain an integer property value.
long	getLong(String name) Obtain a long property value.
JSONObject	getObject(String name) Obtain a JSON object property value.
Object	getProperty(String name) Obtain the value of a property.
String	getString(String name) Obtain a string property value.
JSONLiteral	literal(EncodeControl control) Convert this JSONObject into a JSONLiteral.
JSONArray	optArray(String name) Obtain an array property value or an empty array if the property has no value.
JSONArray	optArray(String name, JSONArray defaultValue) Obtain an array property value or a default value if the property has no value.
boolean	optBoolean(String name, boolean defaultValue) Obtain the boolean value of a property or a default value if the property has no value.
double	optDouble(String name, double defaultValue) Obtain the double value of a property or a default value if the property has no value.
int	optInt(String name, int defaultValue) Obtain the integer value of a property or a default value if the property has no value.
long	optLong(String name, long defaultValue) Obtain the long value of a property or a default value if the property has no value.
JSONObject	optObject(String name) Obtain the JSON object value of a property or an empty object if the property has no value.
JSONObject	optObject(String name, JSONObject defaultValue) Obtain the JSON object value of a property or a default value if the property has no value.
String	optString(String name, String defaultValue) Obtain the string value of a property or a default value if the property has no value.
static JSONObject	parse(String str) Create a JSON object by parsing a JSON object literal string.
Set<Map.Entry<String,Object>>	properties() Get a set view of the properties of this JSON object.
Object	remove(String name) Remove a property from this JSON object.
String	sendableString() Obtain a String representation of this object suitable for output to a connection.
int	size() Return the number of properties in this JSON object.
String	target() Interpreting this JSON object as a JSON message, obtain its target.
String	toString() Obtain a printable string representation of this object.
String	type() Interpreting this JSON object as an encoded object descriptor, obtain its type name.
String	verb() Interpreting this JSON object as a JSON message, obtain its verb.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSONObject

public JSONObject()

Construct a new, empty JSON object.

JSONObject

public JSONObject(Map<String,Object> map)

Construct a JSON object from a pre-existing map.

Parameters:

map - A map mapping JSON property names to their values. All the keys in this map must be strings and the values must be Boolean, Double, Long, String, JSONArray, or JSONObject.

JSONObject

public JSONObject(JSONObject original)

Construct a JSON object by copying another pre-existing JSON object.

Parameters:

original - The original JSON object to be copied.

JSONObject

public JSONObject(String type)

Construct a JSON object representing a typed struct.

Parameters:

type - The type name (this will be added as the property 'type:').

JSONObject

public JSONObject(String target,
                  String verb)

Construct a JSON object representing a message.

Parameters:

target - The reference ID of the message target (this will be added as the property 'to:').

verb - The message verb (this will be added as the property 'op:').

Method Detail

addProperty

public void addProperty(String name,
                        Object value)

Add a property to the object.

Parameters:

name - The name of the property to add.

value - Its value. Although class declaration rules of Java compell 'value' to be declared as class Object, in reality it must be null or one of the classes: Boolean, Double, Long, String, JSONArray, JSONObject.

addProperty

public void addProperty(String name,
                        boolean value)

Add a boolean property to the object.

Parameters:

name - The name of the property to add.

value - Its (boolean) value.

addProperty

public void addProperty(String name,
                        double value)

Add a double property to the object.

Parameters:

name - The name of the property to add.

value - Its (double) value.

addProperty

public void addProperty(String name,
                        int value)

Add an integer property to the object.

Parameters:

name - The name of the property to add.

value - Its (integer) value.

addProperty

public void addProperty(String name,
                        long value)

Add a long property to the object.

Parameters:

name - The name of the property to add.

value - Its (integer) value.

addProperty

public void addProperty(String name,
                        Encodable value)

Add an object that can be encoded as JSON to an object. The value given is encoded, than parsed into a JSON object.

Parameters:

name - The name of the property to add.

value - Its (Encodable) value.

copyProperty

public void copyProperty(String name,
                         JSONObject orig)

Add a property to the object by copying a property of another object. If the object being copied from does not possess the indicated property, this operation has no effect.

Parameters:

name - The name of the property to copy.

orig - The original object to copy from.

getArray

public JSONArray getArray(String name)
                   throws JSONDecodingException

Obtain an array property value.

Parameters:

name - The name of the array property sought.

Returns:

The JSON array value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not an array.

getBoolean

public boolean getBoolean(String name)
                   throws JSONDecodingException

Obtain the boolean value of a property.

Parameters:

name - The name of the boolean property sought.

Returns:

The boolean value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not boolean.

getDouble

public double getDouble(String name)
                 throws JSONDecodingException

Obtain a double property value.

Parameters:

name - The name of the double property sought.

Returns:

The double value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not a number.

getInt

public int getInt(String name)
           throws JSONDecodingException

Obtain an integer property value.

Parameters:

name - The name of the integer property sought.

Returns:

The int value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not a number.

getLong

public long getLong(String name)
             throws JSONDecodingException

Obtain a long property value.

Parameters:

name - The name of the long property sought.

Returns:

The long value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not a number.

getProperty

public Object getProperty(String name)

Obtain the value of a property.

Parameters:

name - The name of the property sought

Returns:

An object representing the value of the property named by 'name', or null if the object has no such property.

getObject

public JSONObject getObject(String name)
                     throws JSONDecodingException

Obtain a JSON object property value.

Parameters:

name - The name of the object property sought.

Returns:

The JSON object value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' or if the value is not a JSON object.

getString

public String getString(String name)
                 throws JSONDecodingException

Obtain a string property value.

Parameters:

name - The name of the string property sought.

Returns:

The string value of the property named by 'name'.

Throws:

JSONDecodingException - if no value is associated with 'name' if the value is not a string.

literal

public JSONLiteral literal(EncodeControl control)

Convert this JSONObject into a JSONLiteral.

Parameters:

control - Encode control determining what flavor of encoding is being done.

optArray

public JSONArray optArray(String name)
                   throws JSONDecodingException

Obtain an array property value or an empty array if the property has no value.

Parameters:

name - The name of the array property sought.

Returns:

The JSON array value of the property named by 'name' or an empty array if the named property has no value.

Throws:

JSONDecodingException - if property has a value but the value is not an array.

optArray

public JSONArray optArray(String name,
                          JSONArray defaultValue)
                   throws JSONDecodingException

Obtain an array property value or a default value if the property has no value.

Parameters:

name - The name of the array property sought.

defaultValue - The value to return if there is no such property.

Returns:

The JSON array value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if property has a value but the value is not an array.

optBoolean

public boolean optBoolean(String name,
                          boolean defaultValue)
                   throws JSONDecodingException

Obtain the boolean value of a property or a default value if the property has no value.

Parameters:

name - The name of the boolean property sought.

defaultValue - The value to return if there is no such property.

Returns:

The boolean value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not boolean.

optDouble

public double optDouble(String name,
                        double defaultValue)
                 throws JSONDecodingException

Obtain the double value of a property or a default value if the property has no value.

Parameters:

name - The name of the double property sought.

defaultValue - The value to return if there is no such property.

Returns:

The double value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a number.

optInt

public int optInt(String name,
                  int defaultValue)
           throws JSONDecodingException

Obtain the integer value of a property or a default value if the property has no value.

Parameters:

name - The name of the integer property sought.

defaultValue - The value to return if there is no such property.

Returns:

The int value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a number.

optLong

public long optLong(String name,
                    long defaultValue)
             throws JSONDecodingException

Obtain the long value of a property or a default value if the property has no value.

Parameters:

name - The name of the long property sought.

defaultValue - The value to return if there is no such property.

Returns:

The long value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a number.

optObject

public JSONObject optObject(String name,
                            JSONObject defaultValue)
                     throws JSONDecodingException

Obtain the JSON object value of a property or a default value if the property has no value.

Parameters:

name - The name of the JSON object property sought.

defaultValue - The value to return if there is no such property.

Returns:

The JSON object value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a JSONObject.

optObject

public JSONObject optObject(String name)
                     throws JSONDecodingException

Obtain the JSON object value of a property or an empty object if the property has no value.

Parameters:

name - The name of the JSON object property sought.

Returns:

The JSON object value of the property named by 'name' or a new empty JSON object if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a JSONObject.

optString

public String optString(String name,
                        String defaultValue)
                 throws JSONDecodingException

Obtain the string value of a property or a default value if the property has no value.

Parameters:

name - The name of the string property sought.

defaultValue - The value to return if there is no such property.

Returns:

The String value of the property named by 'name' or 'defaultValue' if the named property has no value.

Throws:

JSONDecodingException - if the property has a value but the value is not a String.

parse

public static JSONObject parse(String str)
                        throws SyntaxError

Create a JSON object by parsing a JSON object literal string. If this string contains more than one JSON literal, only the first one will be parsed; if you have a string containing more than one JSON literal, use Parser instead.

Parameters:

str - A JSON literal string that will be parsed and turned into the corresponding JSONObject.

Throws:

SyntaxError

properties

public Set<Map.Entry<String,Object>> properties()

Get a set view of the properties of this JSON object.

Returns:

a set of this object's properties.

remove

public Object remove(String name)

Remove a property from this JSON object.

Parameters:

name - The name of the property to remove.

Returns:

the value of the property that was removed or null if there was no such property to remove.

sendableString

public String sendableString()

Obtain a String representation of this object suitable for output to a connection.

Returns:

a sendable String representation of this object

size

public int size()

Return the number of properties in this JSON object.

Returns:

the number properties in this JSON object.

target

public String target()

Interpreting this JSON object as a JSON message, obtain its target.

Returns:

the string value of the 'to' property if it has one, or null.

toString

public String toString()

Obtain a printable string representation of this object.

Overrides:

toString in class Object

Returns:

a printable representation of this object.

type

public String type()

Interpreting this JSON object as an encoded object descriptor, obtain its type name.

Returns:

the string value of the 'type' property if it has one, or null.

verb

public String verb()

Interpreting this JSON object as a JSON message, obtain its verb.

Returns:

the string value of the 'op' property if it has one, or null.