Package oracle.sql.json

Interface OracleJsonArray

  • All Superinterfaces:
    java.util.Collection<OracleJsonValue>, java.lang.Iterable<OracleJsonValue>, java.util.List<OracleJsonValue>, OracleJsonStructure, OracleJsonValue
    public interface OracleJsonArray
extends OracleJsonStructure, java.util.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 Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      void add​(boolean value)
      Appends the specified boolean to the end of this array.
      void add​(byte[] value)
      Appends the specified byte array to the end of this array.
      void add​(double value)
      Appends the specified double to the end of this array.
      void add​(int value)
      Appends the specified integer to the end of this array.
      void add​(long value)
      Appends the specified long to the end of this array.
      void add​(java.lang.String value)
      Appends the specified string to the end of this array.
      void add​(java.math.BigDecimal value)
      Appends the specified decimal to the end of this array.
      void add​(java.time.LocalDateTime value)
      Appends the specified LocalDateTime to the end of this array.
      void add​(java.time.OffsetDateTime value)
      Appends the specified OffsetDateTime to the end of this array.
      void addNull()
      Appends OracleJsonValue.NULL to the end of this array.
      default OracleJsonArray getArray​(int index)
      Returns the array at the specified position in the JSON array.
      java.math.BigDecimal getBigDecimal​(int index)
      Returns the double at the specified position in the JSON array.
      boolean getBoolean​(int index)
      Returns the boolean at the specified position in the JSON array.
      byte[] getBytes​(int index)
      Returns the binary value at the specified position in the JSON array.
      double getDouble​(int index)
      Returns the double at the specified position in the JSON array.
      int getInt​(int index)
      Returns the int at the specified position in the JSON array.
      java.time.LocalDateTime getLocalDateTime​(int index)
      Returns the timestamp or date value at the specified position in the JSON array.
      long getLong​(int index)
      Returns the long at the specified position in the JSON array.
      default OracleJsonObject getObject​(int index)
      Returns the object at the specified position in the JSON array.
      java.time.OffsetDateTime getOffsetDateTime​(int index)
      Returns the timestamptz value at the specified position in the JSON array.
      java.lang.String getString​(int index)
      Returns the string at the specified position in the JSON array.
      <T extends OracleJsonValue>
      java.util.List<T>      		 getValuesAs​(java.lang.Class<T> c)
      Returns a view of this array for the given element type.
      boolean isNull​(int index)
      Returns true if the value at the specified position in the array is equal to JsonValue.NULL.
      OracleJsonValue set​(int index, boolean value)
      Replaces the value at the specified position in the array with the specified boolean.
      OracleJsonValue set​(int index, byte[] value)
      Replaces the value at the specified position in the array with the specified byte array.
      OracleJsonValue set​(int index, double value)
      Replaces the value at the specified position in the array with the specified double.
      OracleJsonValue set​(int index, int value)
      Replaces the value at the specified position in the array with the specified integer.
      OracleJsonValue set​(int index, long value)
      Replaces the value at the specified position in the array with the specified long.
      OracleJsonValue set​(int index, java.lang.String value)
      Replaces the value at the specified position in the array with the specified string.
      OracleJsonValue set​(int index, java.math.BigDecimal value)
      Replaces the value at the specified position in the array with the specified decimal value.
      OracleJsonValue set​(int index, java.time.LocalDateTime value)
      Replaces the value at the specified position in the array with the specified LocalDateTime.
      OracleJsonValue set​(int index, java.time.OffsetDateTime value)
      Replaces the value at the specified position in the array with the specified OffsetDateTime.
      OracleJsonValue setNull​(int index)
      Replaces the value at the specified position in the array with OracleJsonValue.NULL.

      • Methods inherited from interface java.util.Collection

        parallelStream, removeIf, stream, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

      • Methods inherited from interface java.util.List

        add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray

    • Method Detail

      • getString

        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.ClassCastException - if the value at the specified position is not an instance of OracleJsonNumber

      • getBigDecimal

        java.math.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.ClassCastException - if the value at the specified position is not an instance of OracleJsonBinary

      • getLocalDateTime

        java.time.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.ClassCastException - if the value at the specified position is not an instance of OracleJsonTimestamp or OracleJsonDate.

      • getOffsetDateTime

        java.time.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.ClassCastException - if the value at the specified position is not an instance of OracleJsonArray.

      • set

        OracleJsonValue set​(int index,
                    java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • set

        OracleJsonValue set​(int index,
                    java.math.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        OracleJsonException - if the value can not be converted to OracleJsonDecimal
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • set

        OracleJsonValue set​(int index,
                    java.time.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • set

        OracleJsonValue set​(int index,
                    java.time.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.IndexOutOfBoundsException - if the index is out of range
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • add

        void add​(java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • add

        void add​(java.math.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • addNull

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

      • add

        void add​(java.time.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • add

        void add​(java.time.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.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:
        java.lang.NullPointerException - if the specified value is null
        java.lang.UnsupportedOperationException - if the set operation is not supported

      • getValuesAs

        <T extends OracleJsonValue> java.util.List<T> getValuesAs​(java.lang.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