Package com.amazon.ion

Interface IonSequence

All Superinterfaces:
Cloneable, Collection<IonValue>, IonContainer, IonValue, Iterable<IonValue>, List<IonValue>, SequencedCollection<IonValue>
All Known Subinterfaces:
_Private_IonDatagram, IonDatagram, IonList, IonSexp
public interface IonSequence extends IonContainer, List<IonValue>
Common functionality of Ion list and sexp types.

WARNING: This interface should not be implemented or extended by code outside of this library.

Ion sequences implement the standard Java List interface, behaving generally as expected, with the following exceptions:

  • Method Details

    • get

      IonValue get(int index) throws NullValueException, IndexOutOfBoundsException
      Returns the element at the specified position in this sequence.
      Specified by:
      get in interface List<IonValue>
      Parameters:
      index - identifies the element to return.
      Returns:
      the element at the given index; not null.
      Throws:
      NullValueException - if IonValue.isNullValue().
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

    • add

      boolean add(IonValue child) throws ContainedValueException, NullPointerException
      Appends a child value to the end of this sequence. If IonValue.isNullValue(), then it becomes a single-element sequence.
      Specified by:
      add in interface Collection<IonValue>
      Specified by:
      add in interface List<IonValue>
      Parameters:
      child - is the value to be appended to this sequence.
      Returns:
      true (as per the general contract of the Collection.add(E) method).
      Throws:
      NullPointerException - if child is null.
      ContainedValueException - if child is already part of a container.
      IllegalArgumentException - if child is an IonDatagram.

    • add

      ValueFactory add()
      Provides a factory that when invoked constructs a new value and adds it to this sequence.

      These two lines are equivalent: 

          seq.add().newInt(3);
    seq.add(seq.getSystem().newInt(3));

    • add

      void add(int index, IonValue child) throws ContainedValueException, NullPointerException
      Inserts a child value at the specified position in this sequence. If IonValue.isNullValue(), then it becomes a single-element sequence.
      Specified by:
      add in interface List<IonValue>
      Parameters:
      child - is the element to be appended to this sequence.
      Throws:
      NullPointerException - if child is null.
      ContainedValueException - if child is already part of a container.
      IllegalArgumentException - if child is an IonDatagram.
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

    • add

      ValueFactory add(int index)
      Provides a factory that when invoked constructs a new value and adds it to this sequence at the specified position.

      These two lines are equivalent: 

          seq.add(12).newInt(3);
    seq.add(12, seq.getSystem().newInt(3));

      The given index is validated when the factory's creation method is invoked, not when this method is invoked.

    • set

      IonValue set(int index, IonValue element)
      Replaces the element at the specified position in this list with the specified element.
      Specified by:
      set in interface List<IonValue>
      Parameters:
      index - index of the element to replace.
      element - element to be stored at the specified position.
      Returns:
      the element previously at the specified index.
      Throws:
      UnsupportedOperationException - if this is an IonDatagram.
      NullPointerException - if the specified element is null.
      ContainedValueException - if the specified element is already part of a container.
      IllegalArgumentException - if the specified element is an IonDatagram.
      ReadOnlyValueException - if this value or the specified element IonValue.isReadOnly().
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

    • remove

      IonValue remove(int index)
      Removes the element at the specified position. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.
      Specified by:
      remove in interface List<IonValue>
      Parameters:
      index - the index of the element to be removed.
      Returns:
      the element previously at the specified position.
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

    • remove

      boolean remove(Object o)
      Removes a given IonValue from this sequence, if it is present.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead it uses reference equality (== operator) to find the given instance.

      Specified by:
      remove in interface Collection<IonValue>
      Specified by:
      remove in interface List<IonValue>
      Returns:
      true if this sequence changed as a result of the call.
      Throws:
      NullPointerException - if o is null.
      ClassCastException - if o is not an IonValue.

    • removeAll

      boolean removeAll(Collection<?> c)
      Removes all elements from this sequence that are also contained in the specified collection. After this call returns, this sequence will contain no elements in common with the specified collection.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead it uses reference equality (== operator) to find the given instance.

      Specified by:
      removeAll in interface Collection<IonValue>
      Specified by:
      removeAll in interface List<IonValue>
      Returns:
      true if this sequence changed as a result of the call.
      Throws:
      NullPointerException - if c is null.
      NullPointerException - if c contains one or more null elements.
      ClassCastException - if c contains one or more elements that do not implement IonValue.

    • retainAll

      boolean retainAll(Collection<?> c)
      Retains only the elements in this sequence that are also contained in the specified collection. In other words, removes from this sequence all of its elements that are not contained in the specified collection.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead it uses reference equality (== operator) to find the given instance.

      Specified by:
      retainAll in interface Collection<IonValue>
      Specified by:
      retainAll in interface List<IonValue>
      Returns:
      true if this sequence changed as a result of the call.
      Throws:
      NullPointerException - if c is null.
      NullPointerException - if c contains one or more null elements.
      ClassCastException - if c contains one or more elements that do not implement IonValue.

    • contains

      boolean contains(Object o)
      Determines whether this sequence contains the given instance.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead it uses reference equality (== operator) to find the given instance.

      Specified by:
      contains in interface Collection<IonValue>
      Specified by:
      contains in interface List<IonValue>
      Returns:
      true if o is an element of this sequence.
      Throws:
      NullPointerException - if o is null.
      ClassCastException - if o is not an IonValue.

    • containsAll

      boolean containsAll(Collection<?> c)
      Determines whether this sequence contains all of the given instances.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead it uses reference equality (== operator) to find the given instances.

      Specified by:
      containsAll in interface Collection<IonValue>
      Specified by:
      containsAll in interface List<IonValue>
      Returns:
      true if this sequence contains all of the elements of the given collection.
      Throws:
      NullPointerException - if c is null.
      NullPointerException - if c contains one or more null elements.
      ClassCastException - if c contains one or more elements that do not implement IonValue.

    • indexOf

      int indexOf(Object o)
      Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of List. Instead it uses reference equality (== operator) to find the instance.

      Specified by:
      indexOf in interface List<IonValue>
      Parameters:
      o - the element to search for.
      Returns:
      the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

    • lastIndexOf

      int lastIndexOf(Object o)
      Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.

      Due to the reference-equality-based semantics of Ion sequences, this method does not use Object.equals(java.lang.Object) as specified by the contract of List. Instead it uses reference equality (== operator) to find the instance. And since IonSequences do not allow for duplicates this method behaves in the same way as indexOf(Object)

      Specified by:
      lastIndexOf in interface List<IonValue>
      Parameters:
      o - the element to search for.
      Returns:
      the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

    • addAll

      boolean addAll(Collection<? extends IonValue> c)
      Appends all of the elements in the specified collection to the end of this sequence, in the order that they are returned by the collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.)

      Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty IonContainer.

      Specified by:
      addAll in interface Collection<IonValue>
      Specified by:
      addAll in interface List<IonValue>
      Parameters:
      c - elements to be appended to this sequence.
      Returns:
      true if this sequence changed as a result of the call.
      Throws:
      UnsupportedOperationException - if this is an IonDatagram.
      ClassCastException - if one of the elements of the collection is not an IonValue
      NullPointerException - if one of the elements of the collection is null.
      ContainedValueException - if one of the elements is already contained by an IonContainer.

    • addAll

      boolean addAll(int index, Collection<? extends IonValue> c)
      Inserts all of the elements in the specified collection into this sequence at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this sequence in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.)

      Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty IonContainer.

      Specified by:
      addAll in interface List<IonValue>
      Parameters:
      index - index at which to insert first element from the specified collection.
      c - elements to be inserted into this sequence.
      Returns:
      true if this sequence changed as a result of the call.
      Throws:
      UnsupportedOperationException - if this is an IonDatagram.
      ClassCastException - if one of the elements of the collection is not an IonValue
      NullPointerException - if one of the elements of the collection is null.
      ContainedValueException - if one of the elements is already contained by an IonContainer.
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

    • listIterator

      ListIterator<IonValue> listIterator()
      Returns a list iterator of the elements in this sequence (in proper order).

      The result does not support ListIterator.add(Object) or ListIterator.set(Object). If this sequence IonValue.isReadOnly() then it also does not support Iterator.remove().

      Specified by:
      listIterator in interface List<IonValue>

    • listIterator

      ListIterator<IonValue> listIterator(int index)
      Returns a list iterator of the elements in this sequence (in proper order), starting at the specified position in this sequence.

      The result does not support ListIterator.add(Object) or ListIterator.set(Object). If this sequence IonValue.isReadOnly() then it also does not support Iterator.remove().

      Specified by:
      listIterator in interface List<IonValue>
      Parameters:
      index - index of first element to be returned from the list iterator (by a call to the next method).
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

    • subList

      List<IonValue> subList(int fromIndex, int toIndex)

      Returns a view of the portion of this list according to List.subList(int, int) contract.

      Sublist methods will throw a ConcurrentModificationException if its parent list, i.e. this list, had any changes that affect its size the after sublist was created.

      The implementation of List<IonValue> returned by this method implements List.equals(Object) and List.equals(Object) ()} per the specification of these methods. However, the existing implementation of IonSequence does not provide a specification compliant List.equals(java.lang.Object) and List.hashCode()} which results to the following caveats: Given: int[] ints = new int[] {1, 2, 3, 4}; IonList list = SYSTEM.newList(ints); IonSexp sexp = SYSTEM.newSexp(ints) IonSexp dgrm = SYSTEM.newDatagram(ints) List listSubList = list.subList(0, ints.size()) List sexpSubList = sexp.subList(0, ints.size()) List dgrmSubList = sexp.subList(0, ints.size()) List arrayList = new ArrayList(); for(int i : ints) { arrayList.add(SYSTEM.newInt(i)); } IonValue.equals(Object) always returns false when presented with a non IonSequence instance of List<IonValue>. Hence, the following invocations of Object.equals(Object) return false even if the contained elements are equivalent. This means that Object.equals(Object) is not symmetric in these cases. The reason for the asymmetry is historical: IonSequence has long violated the contract outlined by the List documentation. For the current major version of this library we maintain backwards compatibility and support this behaviour as-is. list.equals(listSubList) // false list.equals(sexpSubList) // false list.equals(dgrm) // false list.equals(arrayList) // false sexp.equals(listSubList) // false sexp.equals(sexpSubList) // false sexp.equals(dgrm) // false sexp.equals(arrayList) // false dgrm.equals(listSubList) // false dgrm.equals(sexpSubList) // false dgrm.equals(dgrmSubList) // false dgrm.equals(arrayList) // false However, subList(int, int) was implemented much later and faithfully implements List.equals(Object) meaning the cases below all work as expected. While IonSequence does not comply with the specification for List.equals(Object) because it has to comply with Ion's rules for equality, the same is not true for sub-lists. Unlike IonSequence, sub-lists have no notion of an IonType, annotations or nullability which allows for compliance with the List specification. listSubList.equals(listSubList); // true listSubList.equals(sexpSubList); // true listSubList.equals(dgrmSubList); // true listSubList.equals(list); // true listSubList.equals(sexp); // true listSubList.equals(arrayList); // true sexpSubList.equals(listSubList); // true sexpSubList.equals(sexpSubList); // true sexpSubList.equals(dgrmSubList); // true sexpSubList.equals(list); // true sexpSubList.equals(sexp); // true sexpSubList.equals(arrayList); // true dgrmSubList.equals(listSubList); // true dgrmSubList.equals(sexpSubList); // true dgrmSubList.equals(dgrmSubList); // true dgrmSubList.equals(list); // true dgrmSubList.equals(sexp); // true dgrmSubList.equals(arrayList); // true
      Specified by:
      subList in interface List<IonValue>
      See Also:

    • toArray

      IonValue[] toArray()
      Returns an array containing all of the elements in this sequence in proper order. Obeys the general contract of the Collection.toArray() method.

      If this sequence is an Ion null value, it will behave like an empty sequence.

      Specified by:
      toArray in interface Collection<IonValue>
      Specified by:
      toArray in interface List<IonValue>
      Returns:
      an array containing all of the elements in this sequence in proper order.

    • toArray

      <T> T[] toArray(T[] a)
      Returns an array containing all of the elements in this sequence in proper order; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray() method.

      If this sequence is an Ion null value, it will behave like an empty sequence.

      Specified by:
      toArray in interface Collection<IonValue>
      Specified by:
      toArray in interface List<IonValue>
      Parameters:
      a - the array into which the elements of this sequence 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 all of the elements in this sequence in proper order.
      Throws:
      ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this sequence.
      NullPointerException - if the specified array is null.

    • extract

      <T extends IonValue> T[] extract(Class<T> type)
      Removes all children of this sequence, returning them in an array. This is much more efficient than iterating the sequence and removing children one by one.
      Returns:
      a new array with all of the children of s in order, or null if IonValue.isNullValue().
      Throws:
      NullPointerException - if type is null.
      ClassCastException - if any value in this sequence does not implement the given type.

    • clone

      IonSequence clone() throws UnknownSymbolException
      Description copied from interface: IonValue
      Creates a copy of this value and all of its children. The cloned value may use the same shared symbol tables, but it will have an independent local symbol table if necessary. The cloned value will be modifiable regardless of whether this instance IonValue.isReadOnly().

      The cloned value will be created in the context of the same ValueFactory as this instance; if you want a copy using a different factory, then use ValueFactory.clone(IonValue) instead.

      Specified by:
      clone in interface IonContainer
      Specified by:
      clone in interface IonValue
      Throws:
      UnknownSymbolException - if any part of this value has unknown text but known Sid for its field name, annotation or symbol.