public interface IonSequence extends IonContainer, java.util.List<IonValue>
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:
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.
IonValue instance may be a child of at most one
IonContainer. Instances may be children of any number of
non-Ion Collections.
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).
EMPTY_ARRAY| 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(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.
|
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.
|
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> |
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.
|
clear, isEmpty, iterator, makeNull, remove, sizeaccept, 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, writeToIonValue get(int index) throws NullValueException, java.lang.IndexOutOfBoundsException
get in interface java.util.List<IonValue>index - identifies the element to return.null.NullValueException - if IonValue.isNullValue().java.lang.IndexOutOfBoundsException - if the index is out of range
(index < 0 || index >= size()).boolean add(IonValue child) throws ContainedValueException, java.lang.NullPointerException
IonValue.isNullValue(), then it becomes a single-element
sequence.add in interface java.util.Collection<IonValue>add in interface java.util.List<IonValue>child - is the value to be appended to this sequence.true (as per the general contract of the
Collection.add(E) method).java.lang.NullPointerException - if child is null.ContainedValueException - if child is already part of a container.java.lang.IllegalArgumentException - if child is an IonDatagram.ValueFactory add()
adds it to this sequence.
These two lines are equivalent:
seq.add().newInt(3);
seq.add(seq.getSystem().newInt(3));
void add(int index,
IonValue child)
throws ContainedValueException,
java.lang.NullPointerException
IonValue.isNullValue(), then it becomes a single-element
sequence.add in interface java.util.List<IonValue>child - is the element to be appended to this sequence.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()).ValueFactory add(int index)
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.
IonValue set(int index, IonValue element)
set in interface java.util.List<IonValue>index - index of the element to replace.element - element to be stored at the specified position.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()).IonValue remove(int index)
remove in interface java.util.List<IonValue>index - the index of the element to be removed.java.lang.IndexOutOfBoundsException - if the index is out of range
(index < 0 || index >= size()).boolean remove(java.lang.Object o)
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.
boolean removeAll(java.util.Collection<?> c)
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.
removeAll in interface java.util.Collection<IonValue>removeAll in interface java.util.List<IonValue>true if this sequence changed as a result of the call.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.boolean retainAll(java.util.Collection<?> c)
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.
retainAll in interface java.util.Collection<IonValue>retainAll in interface java.util.List<IonValue>true if this sequence changed as a result of the call.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.boolean contains(java.lang.Object o)
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.
boolean containsAll(java.util.Collection<?> c)
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.
containsAll in interface java.util.Collection<IonValue>containsAll in interface java.util.List<IonValue>true if this sequence contains all of the elements of
the given collection.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.int indexOf(java.lang.Object o)
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.
indexOf in interface java.util.List<IonValue>o - the element to search for.int lastIndexOf(java.lang.Object o)
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)
lastIndexOf in interface java.util.List<IonValue>o - the element to search for.boolean addAll(java.util.Collection<? extends IonValue> c)
Since Ion values can only have a single parent, this method will fail if
the given collection is a non-empty IonContainer.
addAll in interface java.util.Collection<IonValue>addAll in interface java.util.List<IonValue>c - elements to be appended to this sequence.true if this sequence changed as a result of the call.java.lang.UnsupportedOperationException - if this is an IonDatagram.java.lang.ClassCastException - if one of the elements of the collection is not an IonValuejava.lang.NullPointerException - if one of the elements of the collection is null.ContainedValueException - if one of the elements is already contained by an IonContainer.boolean addAll(int index,
java.util.Collection<? extends IonValue> c)
Since Ion values can only have a single parent, this method will fail if
the given collection is a non-empty IonContainer.
addAll in interface java.util.List<IonValue>index - index at which to insert first element from the specified collection.c - elements to be inserted into this sequence.true if this sequence changed as a result of the call.java.lang.UnsupportedOperationException - if this is an IonDatagram.java.lang.ClassCastException - if one of the elements of the collection is not an IonValuejava.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()).java.util.ListIterator<IonValue> listIterator()
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().
listIterator in interface java.util.List<IonValue>java.util.ListIterator<IonValue> listIterator(int index)
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().
listIterator in interface java.util.List<IonValue>index - index of first element to be returned from the list iterator (by a call
to the next method).java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).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.
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
subList in interface java.util.List<IonValue>List.subList(int, int)IonValue[] toArray()
Collection.toArray() method.
If this sequence is an Ion null value, it will behave like an empty sequence.
<T> T[] toArray(T[] a)
Collection.toArray() method.
If this sequence is an Ion null value, it will behave like an empty sequence.
toArray in interface java.util.Collection<IonValue>toArray in interface java.util.List<IonValue>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.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.<T extends IonValue> T[] extract(java.lang.Class<T> type)
s in order, or
null if IonValue.isNullValue().java.lang.NullPointerException - if type is null.java.lang.ClassCastException - if any value in this sequence does not
implement the given type.IonSequence clone() throws UnknownSymbolException
IonValueIonValue.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.
clone in interface IonContainerclone in interface IonValueUnknownSymbolException - if any part of this value has unknown text but known Sid for
its field name, annotation or symbol.