public interface IonReader extends Closeable, Faceted
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 amznlabs/ion-java#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()
.
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) IOException
s specially, then it needs to
extract that from the wrappers; the documentation of IonException
explains how to do that.
Faceted
and implementations may provide additional
functionality accessible via the Faceted.asFacet(Class)
method.
SpanProvider
FacetstepIn()
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.
SeekableReader
FacetInputStream
.
(See issue amznlabs/ion-java#17.)
It allows the user to reposition the reader to a Span
over the
same reader instance or another reader with the same source.
SpanProvider
facet vend Span
s that
are also faceted.
OffsetSpan
FacetTextSpan
FacetModifier and Type | Method and Description |
---|---|
BigDecimal |
bigDecimalValue()
Returns the current value as a
BigDecimal . |
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.
|
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.
|
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.
|
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).
|
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 ). |
Iterator<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.
|
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 . |
IonType next()
*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.
IonType.DATAGRAM
),
or null
when there are no more elements at the current depth in
the same container.void stepIn()
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.
IllegalStateException
- if the current value isn't an Ion container.void stepOut()
next()
to move onto the
following value.IllegalStateException
- if the current value wasn't stepped into.int getDepth()
stepIn()
.SymbolTable getSymbolTable()
IonType getType()
IntegerSize getIntegerSize()
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.IonInt.getIntegerSize()
String[] getTypeAnnotations()
null
) if there are none.UnknownSymbolException
- if any annotation has unknown text.SymbolToken[] getTypeAnnotationSymbols()
null
) if there are none.Iterator<String> iterateTypeAnnotations()
UnknownSymbolException
- if any annotation has unknown text.String getFieldName()
UnknownSymbolException
- if the field name has unknown text.SymbolToken getFieldNameSymbol()
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.boolean isNullValue()
null
or null.int
).
It should be called before
calling getters that return value types (int, long, boolean,
double).boolean isInStruct()
boolean booleanValue()
getType()
returns IonType.BOOL
.int intValue()
long longValue()
BigInteger bigIntegerValue()
BigInteger
. This is only valid if there
is an underlying value and the value is of a numeric type (int, float, or
decimal).double doubleValue()
BigDecimal bigDecimalValue()
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
.
BigDecimal
,
or null
if the current value is null.decimal
.Decimal decimalValue()
Decimal
, which extends
BigDecimal
with support for negative zeros.
This is only valid when getType()
returns
IonType.DECIMAL
.Decimal
,
or null
if the current value is null.decimal
.Date dateValue()
Date
,
or null
if the current value is null.timestamp
.Timestamp timestampValue()
Timestamp
.
This is only valid when getType()
returns
IonType.TIMESTAMP
.Timestamp
,
or null
if the current value is null.timestamp
.String stringValue()
getType()
returns
IonType.STRING
or IonType.SYMBOL
.UnknownSymbolException
- if the current value is a symbol
with unknown text.symbolValue()
SymbolToken symbolValue()
getType()
returns
IonType.SYMBOL
.isNullValue()
int byteSize()
getType()
returns IonType.BLOB
or IonType.CLOB
.byte[] newBytes()
getType()
returns IonType.BLOB
or IonType.CLOB
.int getBytes(byte[] buffer, int offset, int len)
getType()
returns IonType.BLOB
or IonType.CLOB
.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.