Package org.apache.tapestry5.json

Class JSONArray

java.lang.Object

org.apache.tapestry5.json.JSONCollection

org.apache.tapestry5.json.JSONArray

All Implemented Interfaces:

Serializable, Iterable<Object>, Collection<Object>

public final class JSONArray
extends JSONCollection
implements Collection<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	Description
JSONArray()	Creates a JSONArray with no values.
JSONArray(Object... values)	Creates a new JSONArray with values from the given primitive array.
JSONArray(String json)	Creates a new JSONArray with values from the JSON string.

Method Summary

Modifier and Type	Method	Description
boolean	add(Object value)	Appends value to the end of this array.
boolean	addAll(Collection<? extends Object> collection)	Adds all objects from the collection into this JSONArray, using add(Object).
void	clear()	Removes all of the values from this JSONArray.
boolean	contains(Object value)	Returns true if this JSONArray contains the specified value.
boolean	containsAll(Collection<?> c)	Returns true if this JSONArray contains all of the values in the specified collection.
boolean	equals(Object o)
static JSONArray	from(Iterable<?> iterable)	Create a new array, and adds all values from the iterable to the array (using putAll(Iterable).
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.
String	getString(int index)	Returns the value at index if it exists, coercing it if necessary.
int	hashCode()
boolean	isEmpty()	Returns true if this array contains no values.
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.
Iterator<Object>	iterator()	Returns an iterator over the values in this array in proper sequence.
int	length()	Deprecated. Use size() instead.
JSONArray	put(int index, Object value)	Sets the value at index to value, null padding this array to the required length if necessary.
JSONArray	put(Object value)	Deprecated. The use of add(Object) is encouraged.
JSONArray	putAll(Iterable<?> collection)	Puts all objects from the collection into this JSONArray, using put(Object).
Object	remove(int index)	Removes and returns the value at index, or null if the array has no value at index.
boolean	remove(Object value)	Removes the first occurrence of the specified value from this JSONArray, if it is present.
boolean	removeAll(Collection<?> collection)	Removes from this JSONArray all of its values that are contained in the specified collection.
boolean	retainAll(Collection<?> collection)	Retains only the values in this JSONArray that are contained in the specified collection.
int	size()	Returns the number of values in this array.
Object[]	toArray()	Returns an array containing all of the values in this JSONArray in proper sequence.
<T> T[]	toArray(T[] array)	Returns an array containing all of the values in this JSONArray in proper sequence; the runtime type of the returned array is that of the specified array.
List<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.util.Collection

parallelStream, removeIf, spliterator, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

JSONArray

public JSONArray()

Creates a JSONArray with no values.

JSONArray

public JSONArray(String json)

Creates a new JSONArray with values from the JSON string.

Parameters:

json - a JSON-encoded string containing an array.

Throws:

JSONSyntaxException - if the parse fails

JSONTypeMismatchException - if it doesn't yield a JSONArray.

JSONArray

public JSONArray(Object... values)

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

Parameters:

values - The values to use.

Throws:

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

Method Detail

from

public static JSONArray from(Iterable<?> iterable)

Create a new array, and adds all values from 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()

Deprecated.

Use size() instead.

Returns:

Returns the number of values in this array.

size

public int size()

Returns the number of values in this array. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface Collection<Object>

Returns:

the number of values in this array

Since:

5.7

isEmpty

public boolean isEmpty()

Returns true if this array contains no values.

Specified by:

isEmpty in interface Collection<Object>

Returns:

true if this array contains no values

Since:

5.7

put

public JSONArray put(Object value)

Deprecated.

The use of add(Object) is encouraged.

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.

add

public boolean add(Object value)

Appends value to the end of this array.

Specified by:

add in interface Collection<Object>

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:

true (as specified by Collection.add(E))

Since:

5.7

put

public JSONArray put(int index,
                     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:

IllegalArgumentException - If the value cannot be represented as a finite double value.

ArrayIndexOutOfBoundsException - if the index is lower than 0

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 Object get(int index)

Returns the value at index.

Parameters:

index - Which value to get.

Returns:

the value at the specified location.

Throws:

JSONArrayIndexOutOfBoundsException - if the given index is out of bounds.

JSONValueNotFoundException - 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 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.

remove

public boolean remove(Object value)

Removes the first occurrence of the specified value from this JSONArray, if it is present.

Specified by:

remove in interface Collection<Object>

Parameters:

value - value to be removed from this JSONArray, if present

Returns:

true if the element was removed

Since:

5.7

removeAll

public boolean removeAll(Collection<?> collection)

Removes from this JSONArray all of its values that are contained in the specified collection.

Specified by:

removeAll in interface Collection<Object>

Parameters:

collection - collection containing value to be removed from this JSONArray

Returns:

true if this JSONArray changed as a result of the call

Throws:

NullPointerException - if the specified collection is null.

Since:

5.7

See Also:

Collection.contains(Object)

clear

public void clear()

Removes all of the values from this JSONArray.

Specified by:

clear in interface Collection<Object>

Since:

5.7

retainAll

public boolean retainAll(Collection<?> collection)

Retains only the values in this JSONArray that are contained in the specified collection.

Specified by:

retainAll in interface Collection<Object>

Parameters:

collection - collection containing elements to be retained in this list

Returns:

true if this list changed as a result of the call

Since:

5.7

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:

JSONTypeMismatchException - 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:

JSONTypeMismatchException - 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:

JSONTypeMismatchException - 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:

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

getString

public 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:

JSONTypeMismatchException - 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:

JSONTypeMismatchException - 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:

JSONTypeMismatchException - if the value doesn't exist or is not a JSONObject.

equals

public boolean equals(Object o)

Specified by:

equals in interface Collection<Object>

Overrides:

equals in class Object

hashCode

public int hashCode()

Specified by:

hashCode in interface Collection<Object>

Overrides:

hashCode in class Object

putAll

public JSONArray putAll(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

addAll

public boolean addAll(Collection<? extends Object> collection)

Adds all objects from the collection into this JSONArray, using add(Object).

Specified by:

addAll in interface Collection<Object>

Parameters:

collection - Any collection, or null

Returns:

boolean true, if JSONArray was changed.

Since:

5.7

toList

public List<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

toArray

public Object[] toArray()

Returns an array containing all of the values in this JSONArray in proper sequence.

Specified by:

toArray in interface Collection<Object>

Returns:

an array containing all of the values in this JSONArray in proper sequence

Since:

5.7

toArray

public <T> T[] toArray(T[] array)

Returns an array containing all of the values in this JSONArray in proper sequence; the runtime type of the returned array is that of the specified array.

Specified by:

toArray in interface Collection<Object>

Parameters:

array - the array into which the values of this JSONArray are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the values of this JSONArray

Throws:

ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this list

NullPointerException - if the specified array is null

Since:

5.7

iterator

public Iterator<Object> iterator()

Returns an iterator over the values in this array in proper sequence.

Specified by:

iterator in interface Collection<Object>

Specified by:

iterator in interface Iterable<Object>

Returns:

an iterator over the values in this array in proper sequence

contains

public boolean contains(Object value)

Returns true if this JSONArray contains the specified value.

Specified by:

contains in interface Collection<Object>

Parameters:

value - value whose presence in this JSONArray is to be tested

Returns:

true if this JSONArray contains the specified value

Since:

5.7

containsAll

public boolean containsAll(Collection<?> c)

Returns true if this JSONArray contains all of the values in the specified collection.

Specified by:

containsAll in interface Collection<Object>

Parameters:

c - collection to be checked for containment in this collection

Returns:

true if this collection contains all of the elements in the specified collection

Throws:

NullPointerException - if the specified collection is null.

Since:

5.7

See Also:

contains(Object)