public interface IonDatagram extends IonSequence
WARNING: This interface should not be implemented or extended by code outside of this library. Some inherited methods are not yet implemented or are unsupported for datagrams.
Along with the normal user values, datagrams contain system values, notably
the symbol table(s) used to atomize all symbols. Most uses of a datagram
will not see system values,
but applications that need visibility into that data can use the
system*()
methods.
EMPTY_ARRAY
Modifier and Type | Method and Description |
---|---|
ValueFactory |
add(int index)
This inherited method is not yet supported by datagrams.
|
void |
add(int index,
IonValue element)
This inherited method is not yet supported by datagrams.
|
boolean |
addAll(int index,
Collection<? extends IonValue> c)
This inherited method is not yet supported by datagrams.
|
void |
addTypeAnnotation(String annotation)
This inherited method is not supported by datagrams.
|
int |
byteSize()
Gets the number of bytes used to encode this datagram.
|
IonDatagram |
clone()
Creates a copy of this value and all of its children.
|
IonValue |
get(int index)
Gets a selected non-system element from this datagram.
|
byte[] |
getBytes()
Copies the binary-encoded form of this datagram into a new byte array.
|
int |
getBytes(byte[] dst)
Deprecated.
|
int |
getBytes(byte[] dst,
int offset)
Deprecated.
|
int |
getBytes(OutputStream out)
Copies the binary-encoded form of this datagram to a specified stream.
|
IonContainer |
getContainer()
Gets the container of this value,
or
null if this is not part of one. |
SymbolTable |
getSymbolTable()
This inherited method is not supported by datagrams because there's no
single symbol table used across the contents.
|
boolean |
isNullValue()
Returns
false at every call, since datagrams cannot be null. |
Iterator<IonValue> |
iterator()
Creates an iterator providing the (direct) elements of this datagram.
|
void |
makeNull()
This inherited method is not supported by datagrams.
|
IonValue |
set(int index,
IonValue element)
This inherited method is not yet supported by datagrams.
|
int |
size()
Gets the number of elements in the datagram, not counting system
elements.
|
IonValue |
systemGet(int index)
Gets a selected element from this datagram, potentially getting a
hidden system element (such as a symbol table).
|
ListIterator<IonValue> |
systemIterator()
Iterate all values in the datagram, including the otherwise-hidden
system values such as version markers and symbol tables.
|
int |
systemSize()
Gets the number of elements in the datagram, including system elements
such as version markers and symbol tables.
|
byte[] |
toBytes()
Deprecated.
Use
getBytes() instead, which is renamed for consistency with other interfaces. |
add, add, addAll, contains, containsAll, extract, indexOf, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, retainAll, subList, toArray, toArray
clear, isEmpty, remove
accept, clearTypeAnnotations, equals, getFieldId, getFieldName, getFieldNameSymbol, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo
clear, equals, hashCode, isEmpty, replaceAll, sort, spliterator
parallelStream, removeIf, stream
void add(int index, IonValue element) throws ContainedValueException, NullPointerException
Vote for issue amzn/ion-java/issues/48 if you need this.
add
in interface IonSequence
add
in interface List<IonValue>
element
- is the element to be appended to this sequence.UnsupportedOperationException
- at every call.ContainedValueException
- if child
is already part of a container.NullPointerException
- if child
is null
.ValueFactory add(int index) throws ContainedValueException, NullPointerException
Vote for issue amzn/ion-java/issues/48 if you need this.
add
in interface IonSequence
UnsupportedOperationException
- at every call.ContainedValueException
NullPointerException
boolean addAll(int index, Collection<? extends IonValue> c)
Vote for issue amzn/ion-java/issues/47 if you need this.
addAll
in interface IonSequence
addAll
in interface 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.UnsupportedOperationException
- at every call.IonValue set(int index, IonValue element)
Vote for issue amzn/ion-java/issues/50 if you need this.
set
in interface IonSequence
set
in interface List<IonValue>
index
- index of the element to replace.element
- element to be stored at the specified position.UnsupportedOperationException
- at every call.boolean isNullValue()
false
at every call, since datagrams cannot be null.isNullValue
in interface IonValue
false
IonContainer getContainer()
null
if this is not part of one.
Datagrams always return null
from this method, since by
definition they have no container.
getContainer
in interface IonValue
int size()
size
in interface Collection<IonValue>
size
in interface IonContainer
size
in interface List<IonValue>
this.isNullValue()
.int systemSize()
size()
instead.size()
IonValue get(int index) throws IndexOutOfBoundsException
get
in interface IonSequence
get
in interface List<IonValue>
index
- must be less than size()
.null
.IndexOutOfBoundsException
- if the index is bad.IonValue systemGet(int index) throws IndexOutOfBoundsException
get(int)
instead.index
- must be less than systemSize()
.null
.IndexOutOfBoundsException
- if the index is bad.get(int)
Iterator<IonValue> iterator()
This iterator returns only user values, ignoring symbol tables and other
system values. It does not support the Iterator.remove()
operation.
iterator
in interface Collection<IonValue>
iterator
in interface IonContainer
iterator
in interface Iterable<IonValue>
iterator
in interface List<IonValue>
null
.systemIterator()
ListIterator<IonValue> systemIterator()
iterator()
instead.
This iterator does not support the modification methods
Iterator.remove()
, ListIterator.add(Object)
, or
ListIterator.set(Object)
.
iterator()
int byteSize() throws IonException
IonException
- if there's an error encoding the data.@Deprecated byte[] toBytes() throws IonException
getBytes()
instead, which is renamed for consistency with other interfaces.IonException
- if there's an error encoding the data.byte[] getBytes() throws IonException
IonException
- if there's an error encoding the data.@Deprecated int getBytes(byte[] dst) throws IonException
The given array must be large enough to contain all the bytes of this datagram.
An invocation of this method of the form dg.get(a)
behaves in
exactly the same way as the invocation:
dg.get(a, 0)
dst
- the array into which bytes are to be written.dst
.IonException
- if there's an error encoding the data.IndexOutOfBoundsException
- if dst.length
is
smaller than the result of byteSize()
.getBytes(byte[],int)
@Deprecated int getBytes(byte[] dst, int offset) throws IonException
The given subarray must be large enough to contain all the bytes of this datagram.
dst
- the array into which bytes are to be written.offset
- the offset within the array of the first byte to be
written; must be non-negative and no larger than dst.length
dst
.IonException
- if there's an error encoding the data.IndexOutOfBoundsException
- if (dst.length - offset)
is
smaller than the result of byteSize()
.int getBytes(OutputStream out) throws IOException, IonException
out
- the output stream to which to write the data.IonException
- if there's an error encoding the data.IOException
- if an error occurs writing the data to the stream.SymbolTable getSymbolTable()
getSymbolTable
in interface IonValue
UnsupportedOperationException
- at every call.void addTypeAnnotation(String annotation)
addTypeAnnotation
in interface IonValue
annotation
- as a string value.UnsupportedOperationException
- at every call.void makeNull()
makeNull
in interface IonContainer
UnsupportedOperationException
- at every call.IonDatagram clone() throws UnknownSymbolException
IonValue
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.
clone
in interface IonContainer
clone
in interface IonSequence
clone
in interface IonValue
UnknownSymbolException
- if any part of this value has unknown text but known Sid for
its field name, annotation or symbol.