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 Details

  - ### 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 Details

  - ### 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)`