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:
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a JSONArray with no values.
    JSONArray(Object... values)
    Creates a new JSONArray with values from the given primitive array.
    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
    Removes all of the values from this JSONArray.
    boolean
    Returns true if this JSONArray contains the specified value.
    boolean
    Returns true if this JSONArray contains all of the values in the specified collection.
    boolean
     
    static JSONArray
    from(Iterable<?> iterable)
    Create a new array, and adds all values from the iterable to the array (using putAll(Iterable).
    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.
    getJSONArray(int index)
    Returns the value at index if it exists and is a JSONArray.
    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.
    getString(int index)
    Returns the value at index if it exists, coercing it if necessary.
    int
     
    boolean
    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.
    Returns an iterator over the values in this array in proper sequence.
    int
    Deprecated.
    Use size() instead.
    put(int index, Object value)
    Sets the value at index to value, null padding this array to the required length if necessary.
    put(Object value)
    Deprecated.
    The use of add(Object) is encouraged.
    putAll(Iterable<?> collection)
    Puts all objects from the collection into this JSONArray, using put(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
    Returns the number of values in this array.
    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.
    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:
    • 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

      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: