Module com.couchbase.columnar.client.java
Package com.couchbase.columnar.client.java.json

Class JsonArray

java.lang.Object
com.couchbase.columnar.client.java.json.JsonValue
com.couchbase.columnar.client.java.json.JsonArray
All Implemented Interfaces:
Iterable<Object>
public final class JsonArray extends JsonValue implements Iterable<Object>
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.

  • Method Details

    • create

      public static JsonArray create()
      Creates an empty JsonArray.
      Returns:
      an empty JsonArray.

    • create

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

    • from

      public static JsonArray from(Object... items)
      Creates a new JsonArray and populates it with the values supplied.
      Parameters:
      items - the items to be stored in the JsonArray.
      Returns:
      a populated JsonArray.
      Throws:
      IllegalArgumentException - if an element type is not supported.

    • 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:
      IllegalArgumentException - if one or more list elements is of unsupported type.
      NullPointerException - if the given list is null.

    • fromJson

      public static JsonArray fromJson(String jsonArray)
      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:
      jsonArray - the JSON String to convert to a JsonArray.
      Returns:
      the corresponding JsonArray.
      Throws:
      IllegalArgumentException - if the given String is not valid JSON Array.

    • fromJson

      public static JsonArray fromJson(byte[] jsonArray)

    • get

      public @Nullable 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(@Nullable Object value)
      Append an element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.
      Throws:
      IllegalArgumentException - if the value type is not supported.

    • addNull

      public JsonArray addNull()
      Append a null element to the JsonArray.

      This is equivalent to calling add(Object) with null.

      Returns:
      the JsonArray.

    • add

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

    • getString

      public @Nullable 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 @Nullable 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 @Nullable 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 @Nullable 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(@Nullable 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 @Nullable 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(@Nullable JsonArray value)
      Append an JsonArray element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.

    • add

      public JsonArray add(@Nullable 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(@Nullable Number value)
      Append a Number element to the JsonArray.
      Parameters:
      value - the value to append.
      Returns:
      the JsonArray.

    • getArray

      public @Nullable 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 @Nullable 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 @Nullable 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 @Nullable 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<@Nullable 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(@Nullable 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