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>
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:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
Appendsvalue
to the end of this array.boolean
addAll
(Collection<? extends Object> collection) Adds all objects from the collection into this JSONArray, usingadd(Object)
.void
clear()
Removes all of the values from this JSONArray.boolean
Returnstrue
if this JSONArray contains the specified value.boolean
containsAll
(Collection<?> c) Returnstrue
if this JSONArray contains all of the values in the specified collection.boolean
static JSONArray
Create a new array, and adds all values from the iterable to the array (usingputAll(Iterable)
.get
(int index) Returns the value atindex
.boolean
getBoolean
(int index) Returns the value atindex
if it exists and is a boolean or can be coerced to a boolean.double
getDouble
(int index) Returns the value atindex
if it exists and is a double or can be coerced to a double.int
getInt
(int index) Returns the value atindex
if it exists and is an int or can be coerced to an int.getJSONArray
(int index) Returns the value atindex
if it exists and is aJSONArray
.getJSONObject
(int index) Returns the value atindex
if it exists and is aJSONObject
.long
getLong
(int index) Returns the value atindex
if it exists and is a long or can be coerced to a long.getString
(int index) Returns the value atindex
if it exists, coercing it if necessary.int
hashCode()
boolean
isEmpty()
Returnstrue
if this array contains no values.boolean
isNull
(int index) Returns true if this array has no value atindex
, or if its value is thenull
reference orJSONObject.NULL
.iterator()
Returns an iterator over the values in this array in proper sequence.int
length()
Deprecated.Sets the value atindex
tovalue
, null padding this array to the required length if necessary.Deprecated.The use ofadd(Object)
is encouraged.Puts all objects from the collection into this JSONArray, usingput(Object)
.remove
(int index) Removes and returns the value atindex
, or null if the array has no value atindex
.boolean
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.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
-
Constructor Details
-
JSONArray
public JSONArray()Creates aJSONArray
with no values. -
JSONArray
Creates a newJSONArray
with values from the JSON string.- Parameters:
json
- a JSON-encoded string containing an array.- Throws:
JSONSyntaxException
- if the parse failsJSONTypeMismatchException
- if it doesn't yield aJSONArray
.
-
JSONArray
Creates a newJSONArray
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 Details
-
from
Create a new array, and adds all values from the iterable to the array (usingputAll(Iterable)
. This is implemented as a static method so as not to break the semantics of the existingJSONArray(Object...)
constructor. Adding a constructor of type Iterable would change the meaning ofnew JSONArray(new JSONArray())
.- Parameters:
iterable
- collection ot value to include, or null- Since:
- 5.4
-
length
Deprecated.Usesize()
instead.- Returns:
- Returns the number of values in this array.
-
size
Returns the number of values in this array. If this list contains more thanInteger.MAX_VALUE
elements, returnsInteger.MAX_VALUE
.- Specified by:
size
in interfaceCollection<Object>
- Returns:
- the number of values in this array
- Since:
- 5.7
-
isEmpty
Returnstrue
if this array contains no values.- Specified by:
isEmpty
in interfaceCollection<Object>
- Returns:
true
if this array contains no values- Since:
- 5.7
-
put
Deprecated.The use ofadd(Object)
is encouraged.Appendsvalue
to the end of this array.- Parameters:
value
- aJSONObject
,JSONArray
, String, Boolean, Integer, Long, Double, orJSONObject.NULL
}. May not beNaNs
orinfinities
. Unsupported values are not permitted and will cause the array to be in an inconsistent state.- Returns:
- this array.
-
add
Appendsvalue
to the end of this array.- Specified by:
add
in interfaceCollection<Object>
- Parameters:
value
- aJSONObject
,JSONArray
, String, Boolean, Integer, Long, Double, orJSONObject.NULL
}. May not beNaNs
orinfinities
. Unsupported values are not permitted and will cause the array to be in an inconsistent state.- Returns:
true
(as specified byCollection.add(E)
)- Since:
- 5.7
-
put
Sets the value atindex
tovalue
, null padding this array to the required length if necessary. If a value already exists atindex
, it will be replaced.- Parameters:
index
- Where to put the value.value
- aJSONObject
,JSONArray
, String, Boolean, Integer, Long, Double,JSONObject.NULL
, ornull
. May not beNaNs
orinfinities
.- 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
Returns true if this array has no value atindex
, or if its value is thenull
reference orJSONObject.NULL
.- Parameters:
index
- Which value to check.- Returns:
- true if the value is null.
-
get
Returns the value atindex
.- 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 atindex
, or if that value is thenull
reference. This method returns normally if the value isJSONObject#NULL
.
-
remove
Removes and returns the value atindex
, or null if the array has no value atindex
.- Parameters:
index
- Which value to remove.- Returns:
- The value previously at the specified location.
-
remove
Removes the first occurrence of the specified value from this JSONArray, if it is present.- Specified by:
remove
in interfaceCollection<Object>
- Parameters:
value
- value to be removed from this JSONArray, if present- Returns:
true
if the element was removed- Since:
- 5.7
-
removeAll
Removes from this JSONArray all of its values that are contained in the specified collection.- Specified by:
removeAll
in interfaceCollection<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:
-
clear
Removes all of the values from this JSONArray.- Specified by:
clear
in interfaceCollection<Object>
- Since:
- 5.7
-
retainAll
Retains only the values in this JSONArray that are contained in the specified collection.- Specified by:
retainAll
in interfaceCollection<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
Returns the value atindex
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 atindex
doesn't exist or cannot be coerced to a boolean.
-
getDouble
Returns the value atindex
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 atindex
doesn't exist or cannot be coerced to a double.
-
getInt
Returns the value atindex
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 atindex
doesn't exist or cannot be coerced to a int.
-
getLong
Returns the value atindex
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 atindex
doesn't exist or cannot be coerced to a long.
-
getString
Returns the value atindex
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
Returns the value atindex
if it exists and is aJSONArray
.- Parameters:
index
- Which value to get.- Returns:
- the value at the specified location.
- Throws:
JSONTypeMismatchException
- if the value doesn't exist or is not aJSONArray
.
-
getJSONObject
Returns the value atindex
if it exists and is aJSONObject
.- Parameters:
index
- Which value to get.- Returns:
- the value at the specified location.
- Throws:
JSONTypeMismatchException
- if the value doesn't exist or is not aJSONObject
.
-
equals
- Specified by:
equals
in interfaceCollection<Object>
- Overrides:
equals
in classObject
-
hashCode
- Specified by:
hashCode
in interfaceCollection<Object>
- Overrides:
hashCode
in classObject
-
putAll
Puts all objects from the collection into this JSONArray, usingput(Object)
.- Parameters:
collection
- List, array, JSONArray, or other iterable object, or null- Returns:
- this JSONArray
- Since:
- 5.4
-
addAll
Adds all objects from the collection into this JSONArray, usingadd(Object)
.- Specified by:
addAll
in interfaceCollection<Object>
- Parameters:
collection
- Any collection, or null- Returns:
- boolean true, if JSONArray was changed.
- Since:
- 5.7
-
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
Returns an array containing all of the values in this JSONArray in proper sequence.- Specified by:
toArray
in interfaceCollection<Object>
- Returns:
- an array containing all of the values in this JSONArray in proper sequence
- Since:
- 5.7
-
toArray
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 interfaceCollection<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 listNullPointerException
- if the specified array is null- Since:
- 5.7
-
iterator
Returns an iterator over the values in this array in proper sequence. -
contains
Returnstrue
if this JSONArray contains the specified value.- Specified by:
contains
in interfaceCollection<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
Returnstrue
if this JSONArray contains all of the values in the specified collection.- Specified by:
containsAll
in interfaceCollection<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:
-
size()
instead.