Top Description Methods
com.amazon.ion

public Interface IonDatagram

extends IonSequence
Known Direct Subinterfaces
com.amazon.ion.impl._Private_IonDatagram
Known Direct Implementers
com.amazon.ion.impl.lite.IonDatagramLite
Imports
java.io.IOException, .OutputStream, java.util.Collection, .Iterator, .ListIterator
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.

Method Summary

Modifier and TypeMethod and Description
public void
add(int
index at which the specified element is to be inserted
index, IonValue
is the element to be appended to this sequence.
element)

Redeclares com.amazon.ion.IonSequence.add.

This inherited method is not yet supported by datagrams.

public ValueFactory
add(int
element to be appended to this list
index)

Redeclares com.amazon.ion.IonSequence.add.

This inherited method is not yet supported by datagrams.

public boolean
addAll(int
index at which to insert first element from the specified collection.
index, Collection<? extends IonValue>
elements to be inserted into this sequence.
c)

Redeclares com.amazon.ion.IonSequence.addAll.

This inherited method is not yet supported by datagrams.

public void
addTypeAnnotation(String
as a string value.
annotation)

Redeclares com.amazon.ion.IonValue.addTypeAnnotation.

This inherited method is not supported by datagrams.

public int

Returns:

the number of bytes in the binary encoding of this datagram.
byteSize()

Gets the number of bytes used to encode this datagram.

public IonDatagram
clone()

Redeclares com.amazon.ion.IonSequence.clone.

Creates a copy of this value and all of its children.

public IonValue

Returns:

the selected element; not null.
get(int
must be less than size().
index)

Redeclares com.amazon.ion.IonSequence.get.

Gets a selected non-system element from this datagram.

public byte[]

Returns:

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

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

public int

Returns:

the number of bytes copied into dst.
getBytes(byte[]
the array into which bytes are to be written.
dst)
Deprecated

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

public int

Returns:

the number of bytes copied into dst.
getBytes(byte[]
the array into which bytes are to be written.
dst, int
the offset within the array of the first byte to be written; must be non-negative and no larger than dst.length
offset)
Deprecated

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

public int

Returns:

the number of bytes written.
getBytes(OutputStream
the output stream to which to write the data.
out)

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

public IonContainer
getContainer()

Redeclares com.amazon.ion.IonValue.getContainer.

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

public SymbolTable

Returns:

nothing, always throws an exception.
getSymbolTable()

Redeclares com.amazon.ion.IonValue.getSymbolTable.

This inherited method is not supported by datagrams because there's no single symbol table used across the contents.

public boolean

Returns:

false
isNullValue()

Redeclares com.amazon.ion.IonValue.isNullValue.

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

public Iterator<IonValue>
iterator()

Redeclares com.amazon.ion.IonContainer.iterator, java.util.List.iterator.

Creates an iterator providing the (direct) elements of this datagram.

public void
makeNull()

Redeclares com.amazon.ion.IonContainer.makeNull.

This inherited method is not supported by datagrams.

public IonValue
set(int
index of the element to replace.
index, IonValue
element to be stored at the specified position.
element)

Redeclares com.amazon.ion.IonSequence.set.

This inherited method is not yet supported by datagrams.

public int
size()

Redeclares com.amazon.ion.IonContainer.size, java.util.List.size.

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

public IonValue

Returns:

the selected element; not null.
systemGet(int
must be less than systemSize().
index)

Gets a selected element from this datagram, potentially getting a hidden system element (such as a symbol table).

public ListIterator<IonValue>

Returns:

not null.
systemIterator()

Iterate all values in the datagram, including the otherwise-hidden system values such as version markers and symbol tables.

public int
systemSize()

Gets the number of elements in the datagram, including system elements such as version markers and symbol tables.

public byte[]

Returns:

a new, non-empty byte array containing the encoded datagram.
toBytes()
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.

Inherited from com.amazon.ion.IonSequence:
addaddaddAllcontainscontainsAllextractindexOflastIndexOflistIteratorlistIteratorremoveremoveremoveAllretainAllsubListtoArraytoArray

Method Detail

addback to summary
public void add(int index, IonValue element) throws ContainedValueException, NullPointerException

Redeclares com.amazon.ion.IonSequence.add.

This inherited method is not yet supported by datagrams.

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

Parameters
index:int

Doc from java.util.List.add.

index at which the specified element is to be inserted

element:IonValue

Doc from com.amazon.ion.IonSequence.add.

is the element to be appended to this sequence.

Exceptions
ContainedValueException:

Doc from com.amazon.ion.IonSequence.add.

if child is already part of a container.

NullPointerException:

Doc from com.amazon.ion.IonSequence.add.

if child is null.

UnsupportedOperationException:
at every call.
See Also
amazon-ion/ion-java/issues/48
addback to summary
public ValueFactory add(int index) throws ContainedValueException, NullPointerException

Redeclares com.amazon.ion.IonSequence.add.

This inherited method is not yet supported by datagrams.

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

Parameters
index:int

Doc from java.util.List.add.

element to be appended to this list

Returns:ValueFactory

Doc from java.util.List.add.

true (as specified by Collection#add)

Exceptions
NullPointerException:

Doc from java.util.List.add.

if the specified element is null and this list does not permit null elements

UnsupportedOperationException:
at every call.
See Also
amazon-ion/ion-java/issues/48
addAllback to summary
public boolean addAll(int index, Collection<? extends IonValue> c)

Redeclares com.amazon.ion.IonSequence.addAll.

This inherited method is not yet supported by datagrams.

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

Parameters
index:int

Doc from com.amazon.ion.IonSequence.addAll.

index at which to insert first element from the specified collection.

c:Collection<? extends IonValue>

Doc from com.amazon.ion.IonSequence.addAll.

elements to be inserted into this sequence.

Returns:boolean

Doc from com.amazon.ion.IonSequence.addAll.

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

Exceptions
UnsupportedOperationException:
at every call.
See Also
amazon-ion/ion-java/issues/47
addTypeAnnotationback to summary
public void addTypeAnnotation(String annotation)

Redeclares com.amazon.ion.IonValue.addTypeAnnotation.

This inherited method is not supported by datagrams.

Parameters
annotation:String

Doc from com.amazon.ion.IonValue.addTypeAnnotation.

as a string value.

Exceptions
UnsupportedOperationException:
at every call.
byteSizeback to summary
public 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:int

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

Exceptions
IonException:
if there's an error encoding the data.
cloneback to summary
public IonDatagram clone() throws UnknownSymbolException

Redeclares com.amazon.ion.IonSequence.clone.

Doc from com.amazon.ion.IonValue.clone.

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

Exceptions
UnknownSymbolException:
if any part of this value has unknown text but known Sid for its field name, annotation or symbol.
getback to summary
public IonValue get(int index) throws IndexOutOfBoundsException

Redeclares com.amazon.ion.IonSequence.get.

Gets a selected non-system element from this datagram.

Parameters
index:int

must be less than size().

Returns:IonValue

the selected element; not null.

Exceptions
IndexOutOfBoundsException:
if the index is bad.
getBytesback to summary
public byte[] getBytes() throws IonException

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

Returns:byte[]

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

Exceptions
IonException:
if there's an error encoding the data.
getBytesback to summary
public 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:byte[]

the array into which bytes are to be written.

Returns:int

the number of bytes copied into dst.

Annotations
@Deprecated
Exceptions
IonException:
if there's an error encoding the data.
IndexOutOfBoundsException:
if dst.length is smaller than the result of byteSize().
See Also
getBytes(byte[], int)
getBytesback to summary
public 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:byte[]

the array into which bytes are to be written.

offset:int

the offset within the array of the first byte to be written; must be non-negative and no larger than dst.length

Returns:int

the number of bytes copied into dst.

Annotations
@Deprecated
Exceptions
IonException:
if there's an error encoding the data.
IndexOutOfBoundsException:
if (dst.length - offset) is smaller than the result of byteSize().
getBytesback to summary
public int getBytes(OutputStream out) throws IOException, IonException

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

Parameters
out:OutputStream

the output stream to which to write the data.

Returns:int

the number of bytes written.

Exceptions
IOException:
if an error occurs writing the data to the stream.
IonException:
if there's an error encoding the data.
getContainerback to summary
public IonContainer getContainer()

Redeclares com.amazon.ion.IonValue.getContainer.

Doc from com.amazon.ion.IonValue.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.

getSymbolTableback to summary
public SymbolTable getSymbolTable()

Redeclares com.amazon.ion.IonValue.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.

Returns:SymbolTable

nothing, always throws an exception.

Exceptions
UnsupportedOperationException:
at every call.
isNullValueback to summary
public boolean isNullValue()

Redeclares com.amazon.ion.IonValue.isNullValue.

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

Returns:boolean

false

iteratorback to summary
public Iterator<IonValue> iterator()

Redeclares com.amazon.ion.IonContainer.iterator, java.util.List.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.

Returns:Iterator<IonValue>

Doc from com.amazon.ion.IonContainer.iterator.

a new iterator, not null.

See Also
systemIterator()
makeNullback to summary
public void makeNull()

Redeclares com.amazon.ion.IonContainer.makeNull.

This inherited method is not supported by datagrams.

Exceptions
UnsupportedOperationException:
at every call.
setback to summary
public IonValue set(int index, IonValue element)

Redeclares com.amazon.ion.IonSequence.set.

This inherited method is not yet supported by datagrams.

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

Parameters
index:int

Doc from com.amazon.ion.IonSequence.set.

index of the element to replace.

element:IonValue

Doc from com.amazon.ion.IonSequence.set.

element to be stored at the specified position.

Returns:IonValue

Doc from com.amazon.ion.IonSequence.set.

the element previously at the specified index.

Exceptions
UnsupportedOperationException:
at every call.
See Also
amazon-ion/ion-java/issues/50
sizeback to summary
public int size()

Redeclares com.amazon.ion.IonContainer.size, java.util.List.size.

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

Returns:int

Doc from com.amazon.ion.IonContainer.size.

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

systemGetback to summary
public 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:int

must be less than systemSize().

Returns:IonValue

the selected element; not null.

Exceptions
IndexOutOfBoundsException:
if the index is bad.
See Also
get(int)
systemIteratorback to summary
public 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:ListIterator<IonValue>

not null.

See Also
iterator()
systemSizeback to summary
public 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()
toBytesback to summary
public 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:byte[]

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

Annotations
@Deprecated
Exceptions
IonException:
if there's an error encoding the data.