software.amazon.ion

Interface IonSequence

All Superinterfaces:

Cloneable, Collection<IonValue>, IonContainer, IonValue, Iterable<IonValue>, List<IonValue>

All Known Subinterfaces:

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:

• Due to the reference-equality-based semantics of Ion sequences, methods like remove(Object) do not use Object.equals(java.lang.Object) as specified by the contract of Collection. Instead they use reference equality (== operator) to find the given instance.
• Any given IonValue instance may be a child of at most one IonContainer. Instances may be children of any number of non-Ion Collections.
• The method subList(int, int) is not implemented at all. We think it will be quite challenging to get correct, and decided that it was still valuable to extend List even with this contractual violation.

Field Summary

Fields inherited from interface software.amazon.ion.IonValue

EMPTY_ARRAY

Method Summary

Modifier and Type	Method and Description
ValueFactory	add() Provides a factory that when invoked constructs a new value and adds it to this sequence.
ValueFactory	add(int index) Provides a factory that when invoked constructs a new value and adds it to this sequence at the specified position.
void	add(int index, IonValue child) Inserts a child value at the specified position in this sequence.
boolean	add(IonValue child) Appends a child value to the end of this sequence.
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.
boolean	addAll(int index, Collection<? extends IonValue> c) Inserts all of the elements in the specified collection into this sequence at the specified position.
IonSequence	clone() Creates a copy of this value and all of its children.
boolean	contains(Object o) Determines whether this sequence contains the given instance.
boolean	containsAll(Collection<?> c) Determines whether this sequence contains all of the given instances.
<T extends IonValue> T[]	extract(Class<T> type) Removes all children of this sequence, returning them in an array.
IonValue	get(int index) Returns the element at the specified position in this sequence.
int	indexOf(Object o) Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
int	lastIndexOf(Object o) Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
ListIterator<IonValue>	listIterator() Returns a list iterator of the elements in this sequence (in proper order).
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.
IonValue	remove(int index) Removes the element at the specified position.
boolean	remove(Object o) Removes a given IonValue from this sequence, if it is present.
boolean	removeAll(Collection<?> c) Removes all elements from this sequence that are also contained in the specified collection.
boolean	retainAll(Collection<?> c) Retains only the elements in this sequence that are also contained in the specified collection.
IonValue	set(int index, IonValue element) Replaces the element at the specified position in this list with the specified element.
List<IonValue>	subList(int fromIndex, int toIndex) This inherited method is not yet supported.
IonValue[]	toArray() Returns an array containing all of the elements in this sequence in proper order.
<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.

Methods inherited from interface software.amazon.ion.IonContainer

clear, isEmpty, iterator, makeNull, remove, size

Methods inherited from interface software.amazon.ion.IonValue

accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldName, getFieldNameSymbol, getSymbolTable, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isNullValue, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo

Methods inherited from interface java.util.List

clear, equals, hashCode, isEmpty, iterator, replaceAll, size, sort, spliterator

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

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.

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)

This inherited method is not yet supported.

Vote for issue amznlabs/ion-java#52 if you need this.

Specified by:

subList in interface List<IonValue>

Throws:

UnsupportedOperationException - at every call.

See Also:

amznlabs/ion-java#52

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.