Package org.apache.tapestry5.json

Class JSONArray

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<java.lang.Object>, java.util.Collection<java.lang.Object>
    public final class JSONArray
extends JSONCollection
implements java.util.Collection<java.lang.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​(java.lang.Object... values)
      Creates a new JSONArray with values from the given primitive array.
      JSONArray​(java.lang.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​(java.lang.Object value)
      Appends value to the end of this array.
      boolean addAll​(java.util.Collection<? extends java.lang.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​(java.lang.Object value)
      Returns true if this JSONArray contains the specified value.
      boolean containsAll​(java.util.Collection<?> c)
      Returns true if this JSONArray contains all of the values in the specified collection.
      boolean equals​(java.lang.Object o)  
      static JSONArray from​(java.lang.Iterable<?> iterable)
      Create a new array, and adds all values from the iterable to the array (using putAll(Iterable).
      java.lang.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.
      java.lang.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.
      java.util.Iterator<java.lang.Object> iterator()
      Returns an iterator over the values in this array in proper sequence.
      int length()
      Deprecated.
      Use size() instead.
      JSONArray put​(int index, java.lang.Object value)
      Sets the value at index to value, null padding this array to the required length if necessary.
      JSONArray put​(java.lang.Object value)
      Deprecated.
      The use of add(Object) is encouraged.
      JSONArray putAll​(java.lang.Iterable<?> collection)
      Puts all objects from the collection into this JSONArray, using put(Object).
      java.lang.Object remove​(int index)
      Removes and returns the value at index, or null if the array has no value at index.
      boolean remove​(java.lang.Object value)
      Removes the first occurrence of the specified value from this JSONArray, if it is present.
      boolean removeAll​(java.util.Collection<?> collection)
      Removes from this JSONArray all of its values that are contained in the specified collection.
      boolean retainAll​(java.util.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.
      java.lang.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.
      java.util.List<java.lang.Object> toList()
      Returns an unmodifiable list of the contents of the array.

      • 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​(java.lang.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​(java.lang.Object... values)
        Creates a new JSONArray with values from the given primitive array.
        Parameters:
        values - The values to use.
        Throws:
        java.lang.IllegalArgumentException - if any of the values are non-finite double values (i.e. NaN or infinite)

    • Method Detail

      • from

        public static JSONArray from​(java.lang.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 java.util.Collection<java.lang.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 java.util.Collection<java.lang.Object>
        Returns:
        true if this array contains no values
        Since:
        5.7

      • put

        public JSONArray put​(java.lang.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​(java.lang.Object value)
        Appends value to the end of this array.
        Specified by:
        add in interface java.util.Collection<java.lang.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,
                     java.lang.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:
        java.lang.IllegalArgumentException - If the value cannot be represented as a finite double value.
        java.lang.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 java.lang.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 java.lang.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​(java.lang.Object value)
        Removes the first occurrence of the specified value from this JSONArray, if it is present.
        Specified by:
        remove in interface java.util.Collection<java.lang.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​(java.util.Collection<?> collection)
        Removes from this JSONArray all of its values that are contained in the specified collection.
        Specified by:
        removeAll in interface java.util.Collection<java.lang.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:
        java.lang.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 java.util.Collection<java.lang.Object>
        Since:
        5.7

      • retainAll

        public boolean retainAll​(java.util.Collection<?> collection)
        Retains only the values in this JSONArray that are contained in the specified collection.
        Specified by:
        retainAll in interface java.util.Collection<java.lang.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 java.lang.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​(java.lang.Object o)
        Specified by:
        equals in interface java.util.Collection<java.lang.Object>
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Specified by:
        hashCode in interface java.util.Collection<java.lang.Object>
        Overrides:
        hashCode in class java.lang.Object

      • putAll

        public JSONArray putAll​(java.lang.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​(java.util.Collection<? extends java.lang.Object> collection)
        Adds all objects from the collection into this JSONArray, using add(Object).
        Specified by:
        addAll in interface java.util.Collection<java.lang.Object>
        Parameters:
        collection - Any collection, or null
        Returns:
        boolean true, if JSONArray was changed.
        Since:
        5.7

      • toList

        public java.util.List<java.lang.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 java.lang.Object[] toArray()
        Returns an array containing all of the values in this JSONArray in proper sequence.
        Specified by:
        toArray in interface java.util.Collection<java.lang.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 java.util.Collection<java.lang.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:
        java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this list
        java.lang.NullPointerException - if the specified array is null
        Since:
        5.7

      • iterator

        public java.util.Iterator<java.lang.Object> iterator()
        Returns an iterator over the values in this array in proper sequence.
        Specified by:
        iterator in interface java.util.Collection<java.lang.Object>
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.Object>
        Returns:
        an iterator over the values in this array in proper sequence

      • contains

        public boolean contains​(java.lang.Object value)
        Returns true if this JSONArray contains the specified value.
        Specified by:
        contains in interface java.util.Collection<java.lang.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​(java.util.Collection<?> c)
        Returns true if this JSONArray contains all of the values in the specified collection.
        Specified by:
        containsAll in interface java.util.Collection<java.lang.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:
        java.lang.NullPointerException - if the specified collection is null.
        Since:
        5.7
        See Also:
        contains(Object)