Ion Java 1.11.10 · com.amazon.ion.IonReader · APIdia, the JavaDoc alternative

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 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
public BigDecimal	Returns: the current value as a `BigDecimal`, or `null` if the current value is `null.decimal`. bigDecimalValue() Returns the current value as a `BigDecimal`.
public BigInteger	bigIntegerValue() Returns the current value as a `BigInteger`.
public boolean	booleanValue() Returns the current value as an boolean.
public int	Returns: the lob's size in bytes. byteSize() Gets the size in bytes of the current lob value.
public Date	Returns: the current value as a `Date`, or `null` if the current value is `null.timestamp`. dateValue() Returns the current value as a `java.util.Date`.
public Decimal	Returns: the current value as a `Decimal`, or `null` if the current value is `null.decimal`. decimalValue() Returns the current value as a `Decimal`, which extends `BigDecimal` with support for negative zeros.
public double	doubleValue() Returns the current value as a double.
public int	getBytes(byte[] destination to copy the value into, this must not be null. buffer, int the first position to copy into, this must be non null and less than the length of buffer. offset, int 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. len) Copies the current value into the passed in a byte array.
public int	getDepth() Returns the depth into the Ion value that this reader has traversed.
public int	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. getFieldId() Deprecated Use `getFieldNameSymbol()` instead. /** Gets the symbol ID of the field name attached to the current value.
public String	getFieldName() Return the field name of the current value.
public SymbolToken	Returns: null if there is no current value or if the current value is not a field of a struct. getFieldNameSymbol() Gets the current value's field name as a symbol token (text + ID).
public IntegerSize	getIntegerSize() Returns an `IntegerSize` representing the smallest-possible Java type of the Ion `int` at the current value.
public SymbolTable	getSymbolTable() Returns the symbol table that is applicable to the current value.
public IonType	getType() Returns the type of the current value, or null if there is no current value.
public String[]	Returns: the (ordered) annotations on the current value, or an empty array (not `null`) if there are none. getTypeAnnotations() Return the annotations of the current value as an array of strings.
public SymbolToken[]	Returns: the (ordered) annotations on the current value, or an empty array (not `null`) if there are none. getTypeAnnotationSymbols() Gets the current value's annotations as symbol tokens (text + ID).
public 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()`.
public int	intValue() Returns the current value as an int.
public boolean	isInStruct() Determines whether this reader is currently traversing the fields of an Ion struct.
public boolean	isNullValue() Determines whether the current value is a null Ion value of any type (for example, `null` or `null.int`).
public Iterator<String>	Returns: not null. iterateTypeAnnotations() Return the annotations on the curent value as an iterator.
public long	longValue() Returns the current value as a long.
public byte[]	newBytes() Returns the current value as a newly-allocated byte array.
public IonType	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. next() Positions this reader on the next sibling after the current value, returning the type of that value.
public void	stepIn() Positions the reader just before the contents of the current value, which must be a container (list, sexp, or struct).
public void	stepOut() Positions the iterator after the current parent's value, moving up one level in the data hierarchy.
public String	stringValue() Returns the current value as a Java String.
public SymbolToken	Returns: null if `isNullValue()` symbolValue() Returns the current value as a symbol token (text + ID).
public Timestamp	Returns: the current value as a `Timestamp`, or `null` if the current value is `null.timestamp`. timestampValue() Returns the current value as a `Timestamp`.

Inherited from com.amazon.ion.facet.Faceted:: asFacet
Inherited from java.io.Closeable:: close

Method Detail

bigDecimalValue back to summary

bigDecimalValue	back to summary
public 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:BigDecimal the current value as a `BigDecimal`, or `null` if the current value is `null.decimal`.

public 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:BigDecimal: the current value as a BigDecimal, or null if the current value is null.decimal.

bigIntegerValue	back to summary
public 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.

booleanValue	back to summary
public boolean booleanValue() Returns the current value as an boolean. This is only valid when `getType()` returns `IonType#BOOL`.

byteSize back to summary

byteSize	back to summary
public 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:int the lob's size in bytes.

public 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:int: the lob's size in bytes.

dateValue back to summary

dateValue	back to summary
public Date dateValue() Returns the current value as a `java.util.Date`. This is only valid when `getType()` returns `IonType#TIMESTAMP`. Returns:Date the current value as a `Date`, or `null` if the current value is `null.timestamp`.

public Date dateValue()

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

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

decimalValue back to summary

decimalValue	back to summary
public 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:Decimal the current value as a `Decimal`, or `null` if the current value is `null.decimal`.

public 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:Decimal: the current value as a Decimal, or null if the current value is null.decimal.

doubleValue	back to summary
public 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.

getBytes back to summary

getBytes	back to summary
public 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:byte[] destination to copy the value into, this must not be null. offset:int the first position to copy into, this must be non null and less than the length of buffer. len:int 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.

public 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:byte[]: destination to copy the value into, this must not be null.
offset:int: the first position to copy into, this must be non null and less than the length of buffer.
len:int: 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.

getDepth	back to summary
public 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()`.

getFieldId back to summary

getFieldId	back to summary
public 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:int 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. Annotations @Deprecated

public 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:int

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.

Annotations

@Deprecated

getFieldName	back to summary
public 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. Exceptions UnknownSymbolException: if the field name has unknown text.

getFieldName

back to summary

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

Exceptions

UnknownSymbolException:: if the field name has unknown text.

getFieldNameSymbol back to summary

getFieldNameSymbol	back to summary
public 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:SymbolToken null if there is no current value or if the current value is not a field of a struct.

public 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:SymbolToken: null if there is no current value or if the current value is not a field of a struct.

getIntegerSize back to summary

getIntegerSize	back to summary
public 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()`

public 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()

getSymbolTable	back to summary
public SymbolTable getSymbolTable() Returns the symbol table that is applicable to the current value. This may be either a system or local symbol table.

getType	back to summary
public IonType getType() Returns the type of the current value, or null if there is no current value.

getTypeAnnotations back to summary

getTypeAnnotations	back to summary
public String[] getTypeAnnotations() Return the annotations of the current value as an array of strings. Returns:String[] the (ordered) annotations on the current value, or an empty array (not `null`) if there are none. Exceptions UnknownSymbolException: if any annotation has unknown text.

public String[] getTypeAnnotations()

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

Returns:String[]

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

Exceptions

UnknownSymbolException:: if any annotation has unknown text.

getTypeAnnotationSymbols back to summary

getTypeAnnotationSymbols	back to summary
public SymbolToken[] getTypeAnnotationSymbols() Gets the current value's annotations as symbol tokens (text + ID). Returns:SymbolToken[] the (ordered) annotations on the current value, or an empty array (not `null`) if there are none.

public SymbolToken[] getTypeAnnotationSymbols()

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

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

hasNext back to summary

hasNext	back to summary
public 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()`! Annotations @Deprecated

public 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()!

Annotations

@Deprecated

intValue	back to summary
public 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).

isInStruct	back to summary
public 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.

isNullValue	back to summary
public 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).

iterateTypeAnnotations back to summary

iterateTypeAnnotations	back to summary
public Iterator<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:Iterator<String> not null.

public Iterator<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:Iterator<String>: not null.

longValue	back to summary
public 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).

newBytes	back to summary
public byte[] newBytes() Returns the current value as a newly-allocated byte array. This is only valid when `getType()` returns `IonType#BLOB` or `IonType#CLOB`.

next back to summary

next	back to summary
public 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:IonType 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.

public 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:IonType: 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 back to summary

stepIn	back to summary
public 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. Exceptions IllegalStateException: if the current value isn't an Ion container.

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

Exceptions

IllegalStateException:: if the current value isn't an Ion container.

stepOut back to summary

stepOut	back to summary
public 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. Exceptions IllegalStateException: if the current value wasn't stepped into.

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

Exceptions

IllegalStateException:: if the current value wasn't stepped into.

stringValue back to summary

stringValue	back to summary
public String stringValue() Returns the current value as a Java String. This is only valid when `getType()` returns `IonType#STRING` or `IonType#SYMBOL`. Exceptions UnknownSymbolException: if the current value is a symbol with unknown text. See Also `symbolValue()`

public String stringValue()

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

Exceptions

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

See Also

symbolValue()

symbolValue back to summary

symbolValue	back to summary
public SymbolToken symbolValue() Returns the current value as a symbol token (text + ID). This is only valid when `getType()` returns `IonType#SYMBOL`. Returns:SymbolToken null if `isNullValue()`

public SymbolToken symbolValue()

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

Returns:SymbolToken: null if isNullValue()

timestampValue back to summary

timestampValue	back to summary
public Timestamp timestampValue() Returns the current value as a `Timestamp`. This is only valid when `getType()` returns `IonType#TIMESTAMP`. Returns:Timestamp the current value as a `Timestamp`, or `null` if the current value is `null.timestamp`.

public Timestamp timestampValue()

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

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

public Interface IonReader

Exception Handling

Reader Facets

The SpanProvider Facet

The SeekableReader Facet

Span Facets

The OffsetSpan Facet

The TextSpan Facet

Method Summary

Method Detail

The `SpanProvider` Facet

The `SeekableReader` Facet

The `OffsetSpan` Facet

The `TextSpan` Facet