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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    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)`