software.amazon.ion

Interface IonDatagram

All Superinterfaces:

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

public interface IonDatagram
extends IonSequence

A datagram is a "top-level" container of Ion values, and the granularity of binary encoding Ion content.

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.

Field Summary

Fields inherited from interface software.amazon.ion.IonValue

EMPTY_ARRAY

Method Summary

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(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.
boolean	retainAll(Collection<?> c) This inherited method is not yet 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.

Methods inherited from interface software.amazon.ion.IonSequence

add, add, addAll, contains, containsAll, extract, indexOf, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, subList, toArray, toArray

Methods inherited from interface software.amazon.ion.IonContainer

clear, isEmpty, remove

Methods inherited from interface software.amazon.ion.IonValue

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

Methods inherited from interface java.util.List

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

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

add

void add(int index,
         IonValue element)
  throws ContainedValueException,
         NullPointerException

This inherited method is not yet supported by datagrams.

Vote for issue amzn/ion-java#48 if you need this.

Specified by:

add in interface IonSequence

Specified by:

add in interface List<IonValue>

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

Throws:

UnsupportedOperationException - at every call.

ContainedValueException - if child is already part of a container.

NullPointerException - if child is null.

See Also:

amzn/ion-java#48

add

ValueFactory add(int index)
          throws ContainedValueException,
                 NullPointerException

This inherited method is not yet supported by datagrams.

Vote for issue amzn/ion-java#48 if you need this.

Specified by:

add in interface IonSequence

Throws:

UnsupportedOperationException - at every call.

ContainedValueException

NullPointerException

See Also:

amzn/ion-java#48

addAll

boolean addAll(int index,
               Collection<? extends IonValue> c)

This inherited method is not yet supported by datagrams.

Vote for issue amzn/ion-java#47 if you need this.

Specified by:

addAll in interface IonSequence

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 - at every call.

See Also:

amzn/ion-java#47

set

IonValue set(int index,
             IonValue element)

This inherited method is not yet supported by datagrams.

Vote for issue amzn/ion-java#50 if you need this.

Specified by:

set in interface IonSequence

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 - at every call.

See Also:

amzn/ion-java#50

isNullValue

boolean isNullValue()

Returns false at every call, since datagrams cannot be null.

Specified by:

isNullValue in interface IonValue

Returns:

false

getContainer

IonContainer getContainer()

Gets the container of this value, or null if this is not part of one.

Datagrams always return null from this method, since by definition they have no container.

Specified by:

getContainer in interface IonValue

size

int size()

Gets the number of elements in the datagram, not counting system elements.

Specified by:

size in interface Collection<IonValue>

Specified by:

size in interface IonContainer

Specified by:

size in interface List<IonValue>

Returns:

the number of elements, zero if this.isNullValue().

systemSize

int systemSize()

Gets the number of elements in the datagram, including system elements such as version markers and symbol tables. Unless your application needs to be aware of such low-level details, you almost certainly want to use size() instead.

See Also:

size()

get

IonValue get(int index)
      throws IndexOutOfBoundsException

Gets a selected non-system element from this datagram.

Specified by:

get in interface IonSequence

Specified by:

get in interface List<IonValue>

Parameters:

index - must be less than size().

Returns:

the selected element; not null.

Throws:

IndexOutOfBoundsException - if the index is bad.

systemGet

IonValue systemGet(int index)
            throws IndexOutOfBoundsException

Gets a selected element from this datagram, potentially getting a hidden system element (such as a symbol table). Unless your application needs to be aware of such low-level details, you almost certainly want to use get(int) instead.

Parameters:

index - must be less than systemSize().

Returns:

the selected element; not null.

Throws:

IndexOutOfBoundsException - if the index is bad.

See Also:

get(int)

iterator

Iterator<IonValue> iterator()

Creates an iterator providing the (direct) elements of this datagram. Elements will be returned in order of their appearance in the Ion representation.

This iterator returns only user values, ignoring symbol tables and other system values. It does not support the Iterator.remove() operation.

Specified by:

iterator in interface Collection<IonValue>

Specified by:

iterator in interface IonContainer

Specified by:

iterator in interface Iterable<IonValue>

Specified by:

iterator in interface List<IonValue>

Returns:

a new iterator, not null.

See Also:

systemIterator()

systemIterator

ListIterator<IonValue> systemIterator()

Iterate all values in the datagram, including the otherwise-hidden system values such as version markers and symbol tables. Unless your application needs to be aware of such low-level details, you almost certainly want to use iterator() instead.

This iterator does not support the modification methods Iterator.remove(), ListIterator.add(Object), or ListIterator.set(Object).

Returns:

not null.

See Also:

iterator()

byteSize

int byteSize()
      throws IonException

Gets the number of bytes used to encode this datagram. As a side effect, this method encodes the entire datagram into Ion binary format.

Returns:

the number of bytes in the binary encoding of this datagram.

Throws:

IonException - if there's an error encoding the data.

getBytes

byte[] getBytes()
         throws IonException

Copies the binary-encoded form of this datagram into a new byte array.

Returns:

a new, non-empty byte array containing the encoded datagram.

Throws:

IonException - if there's an error encoding the data.

getBytes

int getBytes(OutputStream out)
      throws IOException,
             IonException

Copies the binary-encoded form of this datagram to a specified stream.

Parameters:

out - the output stream to which to write the data.

Returns:

the number of bytes written.

Throws:

IonException - if there's an error encoding the data.

IOException - if an error occurs writing the data to the stream.

getSymbolTable

SymbolTable getSymbolTable()

This inherited method is not supported by datagrams because there's no single symbol table used across the contents. Each value contained by the datagram may have its own symbol table.

Specified by:

getSymbolTable in interface IonValue

Returns:

nothing, always throws an exception.

Throws:

UnsupportedOperationException - at every call.

addTypeAnnotation

void addTypeAnnotation(String annotation)

This inherited method is not supported by datagrams.

Specified by:

addTypeAnnotation in interface IonValue

Parameters:

annotation - as a string value.

Throws:

UnsupportedOperationException - at every call.

makeNull

void makeNull()

This inherited method is not supported by datagrams.

Specified by:

makeNull in interface IonContainer

Throws:

UnsupportedOperationException - at every call.

retainAll

boolean retainAll(Collection<?> c)

This inherited method is not yet supported by datagrams.

Vote for SIM issue amzn/ion-java#49 if you need this.

Specified by:

retainAll in interface Collection<IonValue>

Specified by:

retainAll in interface IonSequence

Specified by:

retainAll in interface List<IonValue>

Returns:

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

Throws:

UnsupportedOperationException - at every call.

See Also:

amzn/ion-java#49

clone

IonDatagram 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 IonSequence

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.