Class JsonArray

java.lang.Object
com.couchbase.client.java.json.JsonValue
com.couchbase.client.java.json.JsonArray
All Implemented Interfaces:
Serializable, Iterable<Object>

public class JsonArray extends JsonValue implements Iterable<Object>, Serializable
Represents a JSON array that can be stored and loaded from Couchbase Server. If boxed return values are unboxed, the calling code needs to make sure to handle potential NullPointerExceptions. The JsonArray is backed by a List and is intended to work similar to it API wise, but to only allow to store such objects which can be represented by JSON.
Since:
2.0
See Also:
  • Method Details

    • create

      public static JsonArray create()
      Creates a empty JsonArray.
      Returns:
      a empty JsonArray.
    • create

      public static JsonArray create(int initialCapacity)
      Creates a empty JsonArray.
      Parameters:
      initialCapacity - the initial capacity for this json array.
      Returns:
      a empty JsonArray.
    • from

      public static JsonArray from(Object... items)
      Creates a new JsonArray and populates it with the values supplied. If the type is not supported, a InvalidArgumentException exception is thrown.
      Parameters:
      items - the items to be stored in the JsonArray.
      Returns:
      a populated JsonArray.
    • from

      public static JsonArray from(List<?> items)
      Returns a new JsonArray containing items from the given List, in the same order they were returned by the list's iterator.

      Sub Maps and Iterables: If possible, contained Maps and Iterables are converted to JsonObject and JsonArray respectively. However, some restrictions apply. Any non-convertible item will raise a ClassCastException. If the sub-conversion raises an exception (like an InvalidArgumentException) then it is put as cause for the ClassCastException.

      Parameters:
      items - the list of items to be stored in the JsonArray.
      Returns:
      a new JsonArray containing the elements from the given list, in the order they were returned by the list's iterator.
      Throws:
      InvalidArgumentException - if one or more items is of unsupported type.
      NullPointerException - if the given list is null.
    • fromJson

      public static JsonArray fromJson(String s)
      Static method to create a JsonArray from a JSON String. Not to be confused with from(Object...) from(aString)} which will populate a new array with the string. The string is expected to be a valid JSON array representation (eg. starting with a '[').
      Parameters:
      s - the JSON String to convert to a JsonArray.
      Returns:
      the corresponding JsonArray.
      Throws:
      InvalidArgumentException - if the conversion cannot be done.
    • fromJson

      public static JsonArray fromJson(byte[] s)
    • get

      public Object get(int index)
      Retrieves the value by the position in the JsonArray and does not cast it.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(Object value)
      Append an element to the JsonArray. Note that the type is checked and a InvalidArgumentException is thrown if not supported.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • addNull

      public JsonArray addNull()
      Append a null element to the JsonArray. This is equivalent to calling add(Object) with null or JsonValue.NULL.
      Returns:
      the JsonArray.
    • add

      public JsonArray add(String value)
      Append an String element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getString

      public String getString(int index)
      Retrieves the value by the position in the JsonArray and casts it to String.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(long value)
      Append an Long element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getLong

      public Long getLong(int index)
      Retrieves the value by the position in the JsonArray and casts it to Long. Note that if value was stored as another numerical type, some truncation or rounding may occur.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(int value)
      Append an Integer element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getInt

      public Integer getInt(int index)
      Retrieves the value by the position in the JsonArray and casts it to Integer. Note that if value was stored as another numerical type, some truncation or rounding may occur.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(double value)
      Append an Double element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getDouble

      public Double getDouble(int index)
      Retrieves the value by the position in the JsonArray and casts it to Double. Note that if value was stored as another numerical type, some truncation or rounding may occur.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(boolean value)
      Append an Boolean element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getBoolean

      public boolean getBoolean(int index)
      Retrieves the value by the position in the JsonArray and casts it to Boolean.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(JsonObject value)
      Append an JsonObject element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • add

      public JsonArray add(Map<String,?> value)
      Append an JsonObject element, converted from a List, to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
      See Also:
    • getObject

      public JsonObject getObject(int index)
      Retrieves the value by the position in the JsonArray and casts it to JsonObject.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • add

      public JsonArray add(JsonArray value)
      Append an JsonArray element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • add

      public JsonArray add(List<?> value)
      Append an JsonArray element, converted from a List, to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
      See Also:
    • add

      public JsonArray add(Number value)
      Append a Number element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
    • getArray

      public JsonArray getArray(int index)
      Retrieves the value by the position in the JsonArray and casts it to JsonArray.
      Parameters:
      index - the index of the value.
      Returns:
      the value at index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • getBigInteger

      public BigInteger getBigInteger(int index)
      Retrieves the value by the position in the JsonArray and casts it to BigInteger.
      Parameters:
      index - the index of the value.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • getBigDecimal

      public BigDecimal getBigDecimal(int index)
      Retrieves the value by the position in the JsonArray and casts it to BigDecimal.
      Parameters:
      index - the index of the value.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • getNumber

      public Number getNumber(int index)
      Retrieves the value by the position in the JsonArray and casts it to Number.
      Parameters:
      index - the index of the value.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or too large.
    • toList

      public List<Object> toList()
      Copies the content of the JsonArray into a new List and returns it. Note that if the array contains sub-JsonObject or JsonArray, they will recursively be converted to Map and List, respectively.
      Returns:
      the content of the JsonArray in a new List.
    • isEmpty

      public boolean isEmpty()
      Checks if the JsonArray is empty or not.
      Returns:
      true if it is, false otherwise.
    • size

      public int size()
      Returns the size of the JsonArray.
      Returns:
      the size.
    • contains

      public boolean contains(Object value)
      Returns true if the object is part of the array.
      Parameters:
      value - the value to check.
      Returns:
      true if it is part of the array, false otherwise.
    • iterator

      public Iterator<Object> iterator()
      Specified by:
      iterator in interface Iterable<Object>
    • toString

      public String toString()
      Converts the JsonArray into its JSON string representation.
      Overrides:
      toString in class Object
      Returns:
      the JSON string representing this JsonArray.
    • toBytes

      public byte[] toBytes()
      Similar to toString() but turns this array directly into an encoded byte array.
      Returns:
      the byte array representing this JsonArray.
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object