org.apache.tapestry5.json

Class JSONArray

java.lang.Object

org.apache.tapestry5.json.JSONCollection

org.apache.tapestry5.json.JSONArray

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<java.lang.Object>

public final class JSONArray
extends JSONCollection
implements java.lang.Iterable<java.lang.Object>

A dense indexed sequence of values. Values may be any mix of JSONObjects, other JSONArrays, Strings, Booleans, Integers, Longs, Doubles, null or JSONObject.NULL. Values may not be NaNs, infinities, or of any type not listed here. JSONArray has the same type coercion behavior and optional/mandatory accessors as JSONObject. See that class' documentation for details. Warning: this class represents null in two incompatible ways: the standard Java null reference, and the sentinel value JSONObject.NULL. In particular, get fails if the requested index holds the null reference, but succeeds if it holds JSONObject.NULL. Instances of this class are not thread safe.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
JSONArray() Creates a JSONArray with no values.
JSONArray(java.lang.Object... values) Creates a new JSONArray with values from the given primitive array.
JSONArray(java.lang.String json) Creates a new JSONArray with values from the JSON string.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o)
static JSONArray	from(java.lang.Iterable<?> iterable) Create a new array, and adds all values fro the iterable to the array (using putAll(Iterable).
java.lang.Object	get(int index) Returns the value at index.
boolean	getBoolean(int index) Returns the value at index if it exists and is a boolean or can be coerced to a boolean.
double	getDouble(int index) Returns the value at index if it exists and is a double or can be coerced to a double.
int	getInt(int index) Returns the value at index if it exists and is an int or can be coerced to an int.
JSONArray	getJSONArray(int index) Returns the value at index if it exists and is a JSONArray.
JSONObject	getJSONObject(int index) Returns the value at index if it exists and is a JSONObject.
long	getLong(int index) Returns the value at index if it exists and is a long or can be coerced to a long.
java.lang.String	getString(int index) Returns the value at index if it exists, coercing it if necessary.
int	hashCode()
boolean	isNull(int index) Returns true if this array has no value at index, or if its value is the null reference or JSONObject.NULL.
java.util.Iterator<java.lang.Object>	iterator()
int	length()
JSONArray	put(int index, java.lang.Object value) Sets the value at index to value, null padding this array to the required length if necessary.
JSONArray	put(java.lang.Object value) Appends value to the end of this array.
JSONArray	putAll(java.lang.Iterable<?> collection) Puts all objects from the collection into this JSONArray, using put(Object).
java.lang.Object	remove(int index) Removes and returns the value at index, or null if the array has no value at index.
java.util.List<java.lang.Object>	toList() Returns an unmodifiable list of the contents of the array.

Methods inherited from class org.apache.tapestry5.json.JSONCollection

prettyPrint, print, print, toCompactString, toString, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

JSONArray

public JSONArray()

Creates a JSONArray with no values.

JSONArray

public JSONArray(java.lang.String json)

Creates a new JSONArray with values from the JSON string.

Parameters:

json - a JSON-encoded string containing an array.

Throws:

java.lang.RuntimeException - if the parse fails or doesn't yield a JSONArray.

JSONArray

public JSONArray(java.lang.Object... values)

Creates a new JSONArray with values from the given primitive array.

Parameters:

values - The values to use.

Throws:

java.lang.RuntimeException - if any of the values are non-finite double values (i.e. NaN or infinite)

Method Detail

from

public static JSONArray from(java.lang.Iterable<?> iterable)

Create a new array, and adds all values fro the iterable to the array (using putAll(Iterable). This is implemented as a static method so as not to break the semantics of the existing JSONArray(Object...) constructor. Adding a constructor of type Iterable would change the meaning of new JSONArray(new JSONArray()).

Parameters:

iterable - collection ot value to include, or null

Since:

5.4

length

public int length()

Returns:

Returns the number of values in this array.

put

public JSONArray put(java.lang.Object value)

Appends value to the end of this array.

Parameters:

value - a JSONObject, JSONArray, String, Boolean, Integer, Long, Double, or JSONObject.NULL}. May not be NaNs or infinities. Unsupported values are not permitted and will cause the array to be in an inconsistent state.

Returns:

this array.

put

public JSONArray put(int index,
                     java.lang.Object value)

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Parameters:

index - Where to put the value.

value - a JSONObject, JSONArray, String, Boolean, Integer, Long, Double, JSONObject.NULL, or null. May not be NaNs or infinities.

Returns:

this array.

Throws:

java.lang.RuntimeException - If the value cannot be represented as a finite double value.

isNull

public boolean isNull(int index)

Returns true if this array has no value at index, or if its value is the null reference or JSONObject.NULL.

Parameters:

index - Which value to check.

Returns:

true if the value is null.

get

public java.lang.Object get(int index)

Returns the value at index.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if this array has no value at index, or if that value is the null reference. This method returns normally if the value is JSONObject#NULL.

remove

public java.lang.Object remove(int index)

Removes and returns the value at index, or null if the array has no value at index.

Parameters:

index - Which value to remove.

Returns:

The value previously at the specified location.

getBoolean

public boolean getBoolean(int index)

Returns the value at index if it exists and is a boolean or can be coerced to a boolean.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value at index doesn't exist or cannot be coerced to a boolean.

getDouble

public double getDouble(int index)

Returns the value at index if it exists and is a double or can be coerced to a double.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value at index doesn't exist or cannot be coerced to a double.

getInt

public int getInt(int index)

Returns the value at index if it exists and is an int or can be coerced to an int.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value at index doesn't exist or cannot be coerced to a int.

getLong

public long getLong(int index)

Returns the value at index if it exists and is a long or can be coerced to a long.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value at index doesn't exist or cannot be coerced to a long.

getString

public java.lang.String getString(int index)

Returns the value at index if it exists, coercing it if necessary.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if no such value exists.

getJSONArray

public JSONArray getJSONArray(int index)

Returns the value at index if it exists and is a JSONArray.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value doesn't exist or is not a JSONArray.

getJSONObject

public JSONObject getJSONObject(int index)

Returns the value at index if it exists and is a JSONObject.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

java.lang.RuntimeException - if the value doesn't exist or is not a JSONObject.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

putAll

public JSONArray putAll(java.lang.Iterable<?> collection)

Puts all objects from the collection into this JSONArray, using put(Object).

Parameters:

collection - List, array, JSONArray, or other iterable object, or null

Returns:

this JSONArray

Since:

5.4

toList

public java.util.List<java.lang.Object> toList()

Returns an unmodifiable list of the contents of the array. This is a wrapper around the list's internal storage and is live (changes to the JSONArray affect the returned List).

Returns:

unmodifiable list of array contents

Since:

5.4

iterator

public java.util.Iterator<java.lang.Object> iterator()

Specified by:

iterator in interface java.lang.Iterable<java.lang.Object>