com.amazon.ion

Interface IonReader

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, Faceted

All Known Subinterfaces:

IonTextReader

public interface IonReader
extends java.io.Closeable, Faceted

Provides stream-based access to Ion data independent of its underlying representation (text, binary, or IonValue tree).

WARNING: This interface should not be implemented or extended by code outside of this library. We still have some work to do before this interface is stable. See issue amazon-ion/ion-java/issues/11

An IonReader has a "cursor" tracking the current value on which the reader is positioned. Generally, newly created readers are not positioned on any value. To begin traversing the Ion data, one would use next() to advance the cursor onto the first value (or learn there isn't one). Once positioned, the current value's data can be accessed with the *Value() methods.

When the current value is a container, calling next() moves the cursor to the next sibling of the container, at the same depth, skipping over any children the container may have. To read the children, call stepIn(), then next() to position onto the first child value (or learn there isn't one). Calling stepOut() skips over any remaining children and moves the cursor just beyond the container; call next() to move the cursor to the following value.

In general, method names are intended to parallel similar methods in the IonValue hierarchy. For example, to get the text of a symbol one would use stringValue(), mirroring IonSymbol.stringValue().

Exception Handling

IonReader is a generic interface for traversing Ion data, and it's not possible to fully specify the set of exceptions that could be thrown from the underlying data source. Thus all failures are thrown as instances of IonException, wrapping the original cause. If an application wants to handle (say) IOExceptions specially, then it needs to extract that from the wrappers; the documentation of IonException explains how to do that.

Reader Facets

Readers are Faceted and implementations may provide additional functionality accessible via the Faceted.asFacet(Class) method.

The SpanProvider Facet

This facet is available on all readers that directly consume an Ion source. It provides access to the "current span" covering the reader's current value. There is not a current span at the start of the source, immediately after a call to stepIn() or stepOut(), or when the prior call to next() returned null (meaning: end of container or end of stream). In such states, SpanProvider.currentSpan() will fail.

The SeekableReader Facet

This facet is available on all readers except those created from an InputStream. (See issue amazon-ion/ion-java/issues/17.) It allows the user to reposition the reader to a Span over the same reader instance or another reader with the same source.

Span Facets

Readers that support the SpanProvider facet vend Spans that are also faceted.

The OffsetSpan Facet

This facet is support by all readers of Ion binary and text data.

The TextSpan Facet

This facet is supported by all readers of Ion text data.

Method Summary

Modifier and Type	Method and Description
java.math.BigDecimal	bigDecimalValue() Returns the current value as a BigDecimal.
java.math.BigInteger	bigIntegerValue() Returns the current value as a BigInteger.
boolean	booleanValue() Returns the current value as an boolean.
int	byteSize() Gets the size in bytes of the current lob value.
java.util.Date	dateValue() Returns the current value as a Date.
Decimal	decimalValue() Returns the current value as a Decimal, which extends BigDecimal with support for negative zeros.
double	doubleValue() Returns the current value as a double.
int	getBytes(byte[] buffer, int offset, int len) Copies the current value into the passed in a byte array.
int	getDepth() Returns the depth into the Ion value that this reader has traversed.
int	getFieldId() Deprecated. Use getFieldNameSymbol() instead.
java.lang.String	getFieldName() Return the field name of the current value.
SymbolToken	getFieldNameSymbol() Gets the current value's field name as a symbol token (text + ID).
IntegerSize	getIntegerSize() Returns an IntegerSize representing the smallest-possible Java type of the Ion int at the current value.
SymbolTable	getSymbolTable() Returns the symbol table that is applicable to the current value.
IonType	getType() Returns the type of the current value, or null if there is no current value.
java.lang.String[]	getTypeAnnotations() Return the annotations of the current value as an array of strings.
SymbolToken[]	getTypeAnnotationSymbols() Gets the current value's annotations as symbol tokens (text + ID).
boolean	hasNext() Deprecated. Applications should detect the end of the current level by checking for a null response from next().
int	intValue() Returns the current value as an int.
boolean	isInStruct() Determines whether this reader is currently traversing the fields of an Ion struct.
boolean	isNullValue() Determines whether the current value is a null Ion value of any type (for example, null or null.int).
java.util.Iterator<java.lang.String>	iterateTypeAnnotations() Return the annotations on the curent value as an iterator.
long	longValue() Returns the current value as a long.
byte[]	newBytes() Returns the current value as a newly-allocated byte array.
IonType	next() Positions this reader on the next sibling after the current value, returning the type of that value.
void	stepIn() Positions the reader just before the contents of the current value, which must be a container (list, sexp, or struct).
void	stepOut() Positions the iterator after the current parent's value, moving up one level in the data hierarchy.
java.lang.String	stringValue() Returns the current value as a Java String.
SymbolToken	symbolValue() Returns the current value as a symbol token (text + ID).
Timestamp	timestampValue() Returns the current value as a Timestamp.

Methods inherited from interface java.io.Closeable

close

Methods inherited from interface com.amazon.ion.facet.Faceted

asFacet

Method Detail

hasNext

@Deprecated
boolean hasNext()

Deprecated. Applications should detect the end of the current level by checking for a null response from next().

Determines whether there is another value at the current depth; in other words whether there is a sibling value that may be reached using next(). This method may be called multiple times, which does not move the current position.

WARNING: this method alters the internal state of the reader such that you cannot reliably get values from the "current" element. The only thing you should call after hasNext() is next()!

next

IonType next()

Positions this reader on the next sibling after the current value, returning the type of that value. Once so positioned the contents of this value can be accessed with the *Value() methods.

A sequence of next() calls traverses the data at a constant depth, within the same container. Use stepIn() to traverse down into any containers, and stepOut() to traverse up to the parent container.

Returns:

the type of the next Ion value (never IonType.DATAGRAM), or null when there are no more elements at the current depth in the same container.

stepIn

void stepIn()

Positions the reader just before the contents of the current value, which must be a container (list, sexp, or struct). There's no current value immediately after stepping in, so the next thing you'll want to do is call next() to move onto the first child value (or learn that there's not one).

Stepping into a null container (null.list, null.sexp, or null.struct) behaves as if the container were empty ([], (), or {}).

At any time stepOut() may be called to move the cursor back to (just after) the parent value, even if there's more children remaining.

Throws:

java.lang.IllegalStateException - if the current value isn't an Ion container.

stepOut

void stepOut()

Positions the iterator after the current parent's value, moving up one level in the data hierarchy. There's no current value immediately after stepping out, so the next thing you'll want to do is call next() to move onto the following value.

Throws:

java.lang.IllegalStateException - if the current value wasn't stepped into.

getDepth

int getDepth()

Returns the depth into the Ion value that this reader has traversed. At top level the depth is 0, and it increases by one on each call to stepIn().

getSymbolTable

SymbolTable getSymbolTable()

Returns the symbol table that is applicable to the current value. This may be either a system or local symbol table.

getType

IonType getType()

Returns the type of the current value, or null if there is no current value.

getIntegerSize

IntegerSize getIntegerSize()

Returns an IntegerSize representing the smallest-possible Java type of the Ion int at the current value. If the current value is null.int or is not an Ion int, or if there is no current value, null will be returned.

See Also:

IonInt.getIntegerSize()

getTypeAnnotations

java.lang.String[] getTypeAnnotations()

Return the annotations of the current value as an array of strings.

Returns:

the (ordered) annotations on the current value, or an empty array (not null) if there are none.

Throws:

UnknownSymbolException - if any annotation has unknown text.

getTypeAnnotationSymbols

SymbolToken[] getTypeAnnotationSymbols()

Gets the current value's annotations as symbol tokens (text + ID).

Returns:

the (ordered) annotations on the current value, or an empty array (not null) if there are none.

iterateTypeAnnotations

java.util.Iterator<java.lang.String> iterateTypeAnnotations()

Return the annotations on the curent value as an iterator. The iterator is empty (hasNext() returns false on the first call) if there are no annotations on the current value.

Implementations *may* throw UnknownSymbolException from this method if any annotation contains unknown text. Alternatively, implementations may provide an Iterator that throws UnknownSymbolException only when the user navigates the iterator to an annotation with unknown text.

Note: the iterator returned by this method is only valid while the reader remains positioned on the current value (i.e., before next, step in, or step out). Use cases that require storing a value's annotations after advancing past that value should either copy them from the iterator or call getTypeAnnotations().

Returns:

not null.

getFieldId

@Deprecated
int getFieldId()

Deprecated. Use getFieldNameSymbol() instead.

/** Gets the symbol ID of the field name attached to the current value.

This is an "expert method": correct use requires deep understanding of the Ion binary format. You almost certainly don't want to use it.

Returns:

the symbol ID of the field name, if the current value is a field within a struct. If the current value is not a field, or if the symbol ID cannot be determined, this method returns a value less than one.

getFieldName

java.lang.String getFieldName()

Return the field name of the current value. Or null if there is no valid current value or if the current value is not a field of a struct.

Throws:

UnknownSymbolException - if the field name has unknown text.

getFieldNameSymbol

SymbolToken getFieldNameSymbol()

Gets the current value's field name as a symbol token (text + ID). If the text of the token isn't known, the result's SymbolToken.getText() will be null. If the symbol ID of the token isn't known, the result's SymbolToken.getSid() will be SymbolTable.UNKNOWN_SYMBOL_ID. At least one of the two fields will be defined.

Returns:

null if there is no current value or if the current value is not a field of a struct.

isNullValue

boolean isNullValue()

Determines whether the current value is a null Ion value of any type (for example, null or null.int). It should be called before calling getters that return value types (int, long, boolean, double).

isInStruct

boolean isInStruct()

Determines whether this reader is currently traversing the fields of an Ion struct. It returns false if the iteration is in a list, a sexp, or a datagram.

booleanValue

boolean booleanValue()

Returns the current value as an boolean. This is only valid when getType() returns IonType.BOOL.

intValue

int intValue()

Returns the current value as an int. This is only valid if there is an underlying value and the value is of a numeric type (int, float, or decimal).

longValue

long longValue()

Returns the current value as a long. This is only valid if there is an underlying value and the value is of a numeric type (int, float, or decimal).

bigIntegerValue

java.math.BigInteger bigIntegerValue()

Returns the current value as a BigInteger. This is only valid if there is an underlying value and the value is of type int or float.

doubleValue

double doubleValue()

Returns the current value as a double. This is only valid if there is an underlying value and the value is either float, or decimal.

bigDecimalValue

java.math.BigDecimal bigDecimalValue()

Returns the current value as a BigDecimal. This method should not return a Decimal, so it lacks support for negative zeros.

This method is only valid when getType() returns IonType.DECIMAL.

Returns:

the current value as a BigDecimal, or null if the current value is null.decimal.

decimalValue

Decimal decimalValue()

Returns the current value as a Decimal, which extends BigDecimal with support for negative zeros. This is only valid when getType() returns IonType.DECIMAL.

Returns:

the current value as a Decimal, or null if the current value is null.decimal.

dateValue

java.util.Date dateValue()

Returns the current value as a Date. This is only valid when getType() returns IonType.TIMESTAMP.

Returns:

the current value as a Date, or null if the current value is null.timestamp.

timestampValue

Timestamp timestampValue()

Returns the current value as a Timestamp. This is only valid when getType() returns IonType.TIMESTAMP.

Returns:

the current value as a Timestamp, or null if the current value is null.timestamp.

stringValue

java.lang.String stringValue()

Returns the current value as a Java String. This is only valid when getType() returns IonType.STRING or IonType.SYMBOL.

Throws:

UnknownSymbolException - if the current value is a symbol with unknown text.

See Also:

symbolValue()

symbolValue

SymbolToken symbolValue()

Returns the current value as a symbol token (text + ID). This is only valid when getType() returns IonType.SYMBOL.

Returns:

null if isNullValue()

byteSize

int byteSize()

Gets the size in bytes of the current lob value. This is only valid when getType() returns IonType.BLOB or IonType.CLOB.

Returns:

the lob's size in bytes.

newBytes

byte[] newBytes()

Returns the current value as a newly-allocated byte array. This is only valid when getType() returns IonType.BLOB or IonType.CLOB.

getBytes

int getBytes(byte[] buffer,
             int offset,
             int len)

Copies the current value into the passed in a byte array. This is only valid when getType() returns IonType.BLOB or IonType.CLOB.

Parameters:

buffer - destination to copy the value into, this must not be null.

offset - the first position to copy into, this must be non null and less than the length of buffer.

len - the number of bytes available in the buffer to copy into, this must be long enough to hold the whole value and not extend outside of buffer.