com.amazon.ion

Interface IonDatagram

All Superinterfaces:

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

All Known Subinterfaces:

_Private_IonDatagram

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 com.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, java.util.Collection<? extends IonValue> c) This inherited method is not yet supported by datagrams.
void	addTypeAnnotation(java.lang.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(java.io.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.
java.util.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).
java.util.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.

Methods inherited from interface com.amazon.ion.IonSequence

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

Methods inherited from interface com.amazon.ion.IonContainer

clear, isEmpty, remove

Methods inherited from interface com.amazon.ion.IonValue

accept, clearTypeAnnotations, equals, getFieldId, 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,
         java.lang.NullPointerException

This inherited method is not yet supported by datagrams.

Vote for issue amazon-ion/ion-java/issues/48 if you need this.

Specified by:

add in interface IonSequence

Specified by:

add in interface java.util.List<IonValue>

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

Throws:

java.lang.UnsupportedOperationException - at every call.

ContainedValueException - if child is already part of a container.

java.lang.NullPointerException - if child is null.

See Also:

amazon-ion/ion-java/issues/48

add

ValueFactory add(int index)
          throws ContainedValueException,
                 java.lang.NullPointerException

This inherited method is not yet supported by datagrams.

Vote for issue amazon-ion/ion-java/issues/48 if you need this.

Specified by:

add in interface IonSequence

Throws:

java.lang.UnsupportedOperationException - at every call.

ContainedValueException

java.lang.NullPointerException

See Also:

amazon-ion/ion-java/issues/48

addAll

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

This inherited method is not yet supported by datagrams.

Vote for issue amazon-ion/ion-java/issues/47 if you need this.

Specified by:

addAll in interface IonSequence

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

See Also:

amazon-ion/ion-java/issues/47

set

IonValue set(int index,
             IonValue element)

This inherited method is not yet supported by datagrams.

Vote for issue amazon-ion/ion-java/issues/50 if you need this.

Specified by:

set in interface IonSequence

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

See Also:

amazon-ion/ion-java/issues/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 java.util.Collection<IonValue>

Specified by:

size in interface IonContainer

Specified by:

size in interface java.util.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 java.lang.IndexOutOfBoundsException

Gets a selected non-system element from this datagram.

Specified by:

get in interface IonSequence

Specified by:

get in interface java.util.List<IonValue>

Parameters:

index - must be less than size().

Returns:

the selected element; not null.

Throws:

java.lang.IndexOutOfBoundsException - if the index is bad.

systemGet

IonValue systemGet(int index)
            throws java.lang.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:

java.lang.IndexOutOfBoundsException - if the index is bad.

See Also:

get(int)

iterator

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

Specified by:

iterator in interface IonContainer

Specified by:

iterator in interface java.lang.Iterable<IonValue>

Specified by:

iterator in interface java.util.List<IonValue>

Returns:

a new iterator, not null.

See Also:

systemIterator()

systemIterator

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

toBytes

@Deprecated
byte[] toBytes()
                    throws IonException

Deprecated. Use getBytes() instead, which is renamed for consistency with other interfaces.

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

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

@Deprecated
int getBytes(byte[] dst)
                  throws IonException

Deprecated.

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

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)

Parameters:

dst - the array into which bytes are to be written.

Returns:

the number of bytes copied into dst.

Throws:

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

java.lang.IndexOutOfBoundsException - if dst.length is smaller than the result of byteSize().

See Also:

getBytes(byte[],int)

getBytes

@Deprecated
int getBytes(byte[] dst,
                         int offset)
                  throws IonException

Deprecated.

Copies the binary-encoded form of this datagram into a given sub-array.

The given subarray must be large enough to contain all the bytes of this datagram.

Parameters:

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

Returns:

the number of bytes copied into dst.

Throws:

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

java.lang.IndexOutOfBoundsException - if (dst.length - offset) is smaller than the result of byteSize().

getBytes

int getBytes(java.io.OutputStream out)
      throws java.io.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.

java.io.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:

java.lang.UnsupportedOperationException - at every call.

addTypeAnnotation

void addTypeAnnotation(java.lang.String annotation)

This inherited method is not supported by datagrams.

Specified by:

addTypeAnnotation in interface IonValue

Parameters:

annotation - as a string value.

Throws:

java.lang.UnsupportedOperationException - at every call.

makeNull

void makeNull()

This inherited method is not supported by datagrams.

Specified by:

makeNull in interface IonContainer

Throws:

java.lang.UnsupportedOperationException - at every call.

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.