Package oracle.sql.json

Interface OracleJsonArray

All Superinterfaces:
Collection<OracleJsonValue>, Iterable<OracleJsonValue>, List<OracleJsonValue>, OracleJsonStructure, OracleJsonValue
public interface OracleJsonArray extends OracleJsonStructure, List<OracleJsonValue>
A JSON array (an ordered sequence of zero or more values). The object may contain any subtype of OracleJsonValue which includes the extended SQL types such as OracleJsonTimestamp.

Instances of OracleJsonArray may either be mutable or immutable. When an instance is immutable, calling methods that would mutate the array will throw UnsupportedOperationException. For example, OracleJsonArray instances that are returned from a ResultSet are immutable. Instances that are returned from OracleJsonFactory.createArray() and OracleJsonFactory.createArray(OracleJsonArray) methods are mutable.

Example: 

  import oracle.sql.json.OracleJsonArray;
  import oracle.sql.json.OracleJsonFactory;
  
  public class JsonArrayExample {
    public static void main(String[] args) {
      OracleJsonFactory factory = new OracleJsonFactory();
  
      OracleJsonArray arr = factory.createArray();
      arr.add("hello");
      arr.add(123);
      arr.add(true);
      
      System.out.println(arr.toString());
      System.out.println(arr.getInt(1));
    }
  }

Running this example prints:

  ["hello",123,true]
  123

  • Method Details

    • getString

      String getString(int index)
      Returns the string at the specified position in the JSON array. This is a convenience method that is equivalent to get(index).asJsonString().getString().
      Parameters:
      index - the index of the JSON string value
      Returns:
      the string value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonString

    • getInt

      int getInt(int index)
      Returns the int at the specified position in the JSON array. This is a convenience method that is equivalent to ((OracleJsonNumber)get(index)).intValue().
      Parameters:
      index - the index of the JSON value
      Returns:
      the int value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonNumber

    • getDouble

      double getDouble(int index)
      Returns the double at the specified position in the JSON array. This is a convenience method that is equivalent to ((OracleJsonNumber)get(index)).doubleValue().
      Parameters:
      index - the index of the JSON value
      Returns:
      the double value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonNumber

    • getBigDecimal

      BigDecimal getBigDecimal(int index)
      Returns the double at the specified position in the JSON array. This is a convenience method that is equivalent to ((OracleJsonNumber)get(index)).bigDecimalValue().
      Parameters:
      index - the index of the JSON value
      Returns:
      the BigDecimal value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonNumber

    • getLong

      long getLong(int index)
      Returns the long at the specified position in the JSON array. This is a convenience method that is equivalent to ((OracleJsonNumber)get(index)).longValue().
      Parameters:
      index - the index of the JSON value
      Returns:
      the long value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonNumber

    • getBoolean

      boolean getBoolean(int index)
      Returns the boolean at the specified position in the JSON array. Specifically, returns true if the value at the specified position is equal to OracleJsonValue.TRUE and false if the value at the specified position is equal to OracleJsonValue.FALSE.
      Parameters:
      index - the index of the JSON value
      Returns:
      the boolean value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not equal to OracleJsonValue.TRUE or OracleJson.FALSE.

    • isNull

      boolean isNull(int index)
      Returns true if the value at the specified position in the array is equal to JsonValue.NULL.
      Parameters:
      index - the index of the JSON value
      Returns:
      the boolean value
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • getBytes

      byte[] getBytes(int index)
      Returns the binary value at the specified position in the JSON array. This is a convenience method that is equivalent to get(index).asJsonBinary().getBytes().
      Parameters:
      index - the index of the JSON value
      Returns:
      the binary value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonBinary

    • getLocalDateTime

      LocalDateTime getLocalDateTime(int index)
      Returns the timestamp or date value at the specified position in the JSON array. The method is equivalent to get(index).asJsonDate().getLocalDateTime() or get(index).asJsonTimestamp().getLocalDateTime() depending if the value is a date or a timestamp.
      Parameters:
      index - the index of the JSON value
      Returns:
      the string value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonTimestamp or OracleJsonDate.

    • getOffsetDateTime

      OffsetDateTime getOffsetDateTime(int index)
      Returns the timestamptz value at the specified position in the JSON array. This is a convenience method that is equivalent to get(index).asJsonTimestampTZ().getOffsetDateTime().
      Parameters:
      index - the index of the JSON value
      Returns:
      the string value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonDateTime.

    • getObject

      default OracleJsonObject getObject(int index)
      Returns the object at the specified position in the JSON array. This is a convenience method that is equivalent to get(index).asJsonObject().
      Parameters:
      index - the index of the JSON value
      Returns:
      the string value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonObject.

    • getArray

      default OracleJsonArray getArray(int index)
      Returns the array at the specified position in the JSON array. This is a convenience method that is equivalent to get(index).asJsonArray().
      Parameters:
      index - the index of the JSON value
      Returns:
      the string value
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      ClassCastException - if the value at the specified position is not an instance of OracleJsonArray.

    • set

      OracleJsonValue set(int index, String value)
      Replaces the value at the specified position in the array with the specified string. The new string is added to the array as an instance of OracleJsonString.
      Parameters:
      index - the index of the JSON value to replace
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, int value)
      Replaces the value at the specified position in the array with the specified integer. The new int is added to the array as an instance of OracleJsonDecimal.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, double value)
      Replaces the value at the specified position in the array with the specified double. The new double is added to the array as an instance of OracleJsonDouble.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, long value)
      Replaces the value at the specified position in the array with the specified long. The new long is added to the array as an instance of OracleJsonDecimal.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, BigDecimal value) throws OracleJsonException
      Replaces the value at the specified position in the array with the specified decimal value. The new value is added to the array as an instance of OracleJsonDecimal.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      OracleJsonException - if the value can not be converted to OracleJsonDecimal
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, boolean value)
      Replaces the value at the specified position in the array with the specified boolean. If the specified value is true, then OracleJsonValue.TRUE is added and otherwise OracleJsonValue.FALSE.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • setNull

      OracleJsonValue setNull(int index)
      Replaces the value at the specified position in the array with OracleJsonValue.NULL.
      Parameters:
      index - the index of the JSON value to replace
      Returns:
      the value previously at the specified position
      Throws:
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, LocalDateTime value)
      Replaces the value at the specified position in the array with the specified LocalDateTime. The LocalDateTime is added to the array as an instance of OracleJsonTimestamp.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, OffsetDateTime value)
      Replaces the value at the specified position in the array with the specified OffsetDateTime. The OffsetDateTime is added to the array as an instance of OracleJsonTimestampTZ.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • set

      OracleJsonValue set(int index, byte[] value)
      Replaces the value at the specified position in the array with the specified byte array. The byte array is added to the array as an instance of OracleJsonBinary.
      Parameters:
      index - the index of the JSON value to replace
      value - the value to be set at the specified position
      Returns:
      the value previously at the specified position
      Throws:
      NullPointerException - if the specified value is null
      IndexOutOfBoundsException - if the index is out of range
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(String value)
      Appends the specified string to the end of this array. The string is appended to the array as an instance of OracleJsonString.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(int value)
      Appends the specified integer to the end of this array. The int is appended to the array as an instance of OracleJsonDecimal.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(double value)
      Appends the specified double to the end of this array. The double is appended to the array as an instance of OracleJsonDouble.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(long value)
      Appends the specified long to the end of this array. The long is appended to the array as an instance of OracleJsonDecimal.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(BigDecimal value)
      Appends the specified decimal to the end of this array. The decimal is appended to the array as an instance of OracleJsonDecimal.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(boolean value)
      Appends the specified boolean to the end of this array. If the specified value is true then OracleJsonValue.TRUE is appended to the list and otherwise OracleJsonValue.FALSE.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • addNull

      void addNull()
      Appends OracleJsonValue.NULL to the end of this array.
      Throws:
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(LocalDateTime value)
      Appends the specified LocalDateTime to the end of this array. The LocalDateTime is appended to the array as an instance of OracleJsonTimestamp.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(OffsetDateTime value)
      Appends the specified OffsetDateTime to the end of this array. The OffsetDateTime is appended to the array as an instance of OracleJsonTimestampTZ.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • add

      void add(byte[] value)
      Appends the specified byte array to the end of this array. The byte array is appended to the array as an instance of OracleJsonBinary.
      Parameters:
      value - the value to be appended to this array
      Throws:
      NullPointerException - if the specified value is null
      UnsupportedOperationException - if the set operation is not supported

    • getValuesAs

      <T extends OracleJsonValue> List<T> getValuesAs(Class<T> c)
      Returns a view of this array for the given element type.
      Parameters:
      c - a subtype of OracleJsonValue
      Returns:
      the view of this array