Package com.amazon.ion

Interface IonSequence

All Superinterfaces:

java.lang.Cloneable, java.util.Collection<IonValue>, IonContainer, IonValue, java.lang.Iterable<IonValue>, java.util.List<IonValue>

All Known Subinterfaces:

_Private_IonDatagram, IonDatagram, IonList, IonSexp

public interface IonSequence
extends IonContainer, java.util.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 implementations of List.equals(Object)} and List.hashCode() does not conform to the specification of those methods in order to conform with Ion's definition of equality which takes into account the IonSequence's IonType and its annotations in addition to the contents of the collection.
  • List.equals(Object) always returns false for any non-IonSequence implementation of List, including the sub-list returned from subList(int, int).
  • List.hashCode() returns a different hash code than other List.hashCode() implementations. including the sub-list returned from subList(int, int).

Field Summary

Fields inherited from interface com.amazon.ion.IonValue

EMPTY_ARRAY

Method Summary

Modifier and Type	Method	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(int index, java.util.Collection<? extends IonValue> c)	Inserts all of the elements in the specified collection into this sequence at the specified position.
boolean	addAll(java.util.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.
IonSequence	clone()	Creates a copy of this value and all of its children.
boolean	contains(java.lang.Object o)	Determines whether this sequence contains the given instance.
boolean	containsAll(java.util.Collection<?> c)	Determines whether this sequence contains all of the given instances.
<T extends IonValue> T[]	extract(java.lang.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(java.lang.Object o)	Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
int	lastIndexOf(java.lang.Object o)	Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
java.util.ListIterator<IonValue>	listIterator()	Returns a list iterator of the elements in this sequence (in proper order).
java.util.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(java.lang.Object o)	Removes a given IonValue from this sequence, if it is present.
boolean	removeAll(java.util.Collection<?> c)	Removes all elements from this sequence that are also contained in the specified collection.
boolean	retainAll(java.util.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.
java.util.List<IonValue>	subList(int fromIndex, int toIndex)	Returns a view of the portion of this list according to List.subList(int, int) contract.
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 java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface com.amazon.ion.IonContainer

clear, isEmpty, iterator, makeNull, remove, size

Methods inherited from interface com.amazon.ion.IonValue

accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldId, 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.lang.Iterable

forEach

Methods inherited from interface java.util.List

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

Method Detail

get

IonValue get(int index)
      throws NullValueException,
             java.lang.IndexOutOfBoundsException

Returns the element at the specified position in this sequence.

Specified by:

get in interface java.util.List<IonValue>

Parameters:

index - identifies the element to return.

Returns:

the element at the given index; not null.

Throws:

NullValueException - if IonValue.isNullValue().

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

add

boolean add(IonValue child)
     throws ContainedValueException,
            java.lang.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 java.util.Collection<IonValue>

Specified by:

add in interface java.util.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:

java.lang.NullPointerException - if child is null.

ContainedValueException - if child is already part of a container.

java.lang.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,
         java.lang.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 java.util.List<IonValue>

Parameters:

child - is the element to be appended to this sequence.

Throws:

java.lang.NullPointerException - if child is null.

ContainedValueException - if child is already part of a container.

java.lang.IllegalArgumentException - if child is an IonDatagram.

java.lang.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 java.util.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:

java.lang.UnsupportedOperationException - if this is an IonDatagram.

java.lang.NullPointerException - if the specified element is null.

ContainedValueException - if the specified element is already part of a container.

java.lang.IllegalArgumentException - if the specified element is an IonDatagram.

ReadOnlyValueException - if this value or the specified element IonValue.isReadOnly().

java.lang.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 java.util.List<IonValue>

Parameters:

index - the index of the element to be removed.

Returns:

the element previously at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

remove

boolean remove(java.lang.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 java.util.Collection<IonValue>

Specified by:

remove in interface java.util.List<IonValue>

Returns:

true if this sequence changed as a result of the call.

Throws:

java.lang.NullPointerException - if o is null.

java.lang.ClassCastException - if o is not an IonValue.

removeAll

boolean removeAll(java.util.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 java.util.Collection<IonValue>

Specified by:

removeAll in interface java.util.List<IonValue>

Returns:

true if this sequence changed as a result of the call.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.NullPointerException - if c contains one or more null elements.

java.lang.ClassCastException - if c contains one or more elements that do not implement IonValue.

retainAll

boolean retainAll(java.util.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 java.util.Collection<IonValue>

Specified by:

retainAll in interface java.util.List<IonValue>

Returns:

true if this sequence changed as a result of the call.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.NullPointerException - if c contains one or more null elements.

java.lang.ClassCastException - if c contains one or more elements that do not implement IonValue.

contains

boolean contains(java.lang.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 java.util.Collection<IonValue>

Specified by:

contains in interface java.util.List<IonValue>

Returns:

true if o is an element of this sequence.

Throws:

java.lang.NullPointerException - if o is null.

java.lang.ClassCastException - if o is not an IonValue.

containsAll

boolean containsAll(java.util.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 java.util.Collection<IonValue>

Specified by:

containsAll in interface java.util.List<IonValue>

Returns:

true if this sequence contains all of the elements of the given collection.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.NullPointerException - if c contains one or more null elements.

java.lang.ClassCastException - if c contains one or more elements that do not implement IonValue.

indexOf

int indexOf(java.lang.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 java.util.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(java.lang.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 java.util.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(java.util.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 java.util.Collection<IonValue>

Specified by:

addAll in interface java.util.List<IonValue>

Parameters:

c - elements to be appended to this sequence.

Returns:

true if this sequence changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if this is an IonDatagram.

java.lang.ClassCastException - if one of the elements of the collection is not an IonValue

java.lang.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,
               java.util.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 java.util.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:

java.lang.UnsupportedOperationException - if this is an IonDatagram.

java.lang.ClassCastException - if one of the elements of the collection is not an IonValue

java.lang.NullPointerException - if one of the elements of the collection is null.

ContainedValueException - if one of the elements is already contained by an IonContainer.

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

listIterator

java.util.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 java.util.List<IonValue>

listIterator

java.util.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 java.util.List<IonValue>

Parameters:

index - index of first element to be returned from the list iterator (by a call to the next method).

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

subList

java.util.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 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. 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 java.util.List<IonValue>

See Also:

List.subList(int, int)

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 java.util.Collection<IonValue>

Specified by:

toArray in interface java.util.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 java.util.Collection<IonValue>

Specified by:

toArray in interface java.util.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:

java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this sequence.

java.lang.NullPointerException - if the specified array is null.

extract

<T extends IonValue> T[] extract(java.lang.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:

java.lang.NullPointerException - if type is null.

java.lang.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.