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

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method	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.
    
    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.

Interface IonReader

Exception Handling

Reader Facets

The SpanProvider Facet

The SeekableReader Facet

Span Facets

The OffsetSpan Facet

The TextSpan Facet

Method Summary

Methods inherited from interface java.io.Closeable

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

Method Detail

hasNext

next

stepIn

stepOut

getDepth

getSymbolTable

getType

getIntegerSize

getTypeAnnotations

getTypeAnnotationSymbols

iterateTypeAnnotations

getFieldId

getFieldName

getFieldNameSymbol

isNullValue

isInStruct

booleanValue

intValue

longValue

bigIntegerValue

doubleValue

bigDecimalValue

decimalValue

dateValue

timestampValue

stringValue

symbolValue

byteSize

newBytes

getBytes

The `SpanProvider` Facet

The `SeekableReader` Facet

The `OffsetSpan` Facet

The `TextSpan` Facet