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, orIonValue
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 usenext()
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, callstepIn()
, thennext()
to position onto the first child value (or learn there isn't one). CallingstepOut()
skips over any remaining children and moves the cursor just beyond the container; callnext()
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 usestringValue()
, mirroringIonSymbol.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 ofIonException
, 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 ofIonException
explains how to do that.Reader Facets
Readers areFaceted
and implementations may provide additional functionality accessible via theFaceted.asFacet(Class)
method.The
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 toSpanProvider
FacetstepIn()
orstepOut()
, or when the prior call tonext()
returned null (meaning: end of container or end of stream). In such states,SpanProvider.currentSpan()
will fail.The
This facet is available on all readers except those created from anSeekableReader
FacetInputStream
. (See issue amazon-ion/ion-java/issues/17.) It allows the user to reposition the reader to aSpan
over the same reader instance or another reader with the same source.Span Facets
Readers that support theSpanProvider
facet vendSpan
s that are also faceted.The
This facet is support by all readers of Ion binary and text data.OffsetSpan
FacetThe
This facet is supported by all readers of Ion text data.TextSpan
Facet
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description java.math.BigDecimal
bigDecimalValue()
Returns the current value as aBigDecimal
.java.math.BigInteger
bigIntegerValue()
Returns the current value as aBigInteger
.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 aDate
.Decimal
decimalValue()
Returns the current value as aDecimal
, which extendsBigDecimal
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.UsegetFieldNameSymbol()
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 anIntegerSize
representing the smallest-possible Java type of the Ionint
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 anull
response fromnext()
.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
ornull.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 aTimestamp
.
-
-
-
Method Detail
-
hasNext
@Deprecated boolean hasNext()
Deprecated.Applications should detect the end of the current level by checking for anull
response fromnext()
.Determines whether there is another value at the current depth; in other words whether there is a sibling value that may be reached usingnext()
. 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()
isnext()
!
-
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. UsestepIn()
to traverse down into any containers, andstepOut()
to traverse up to the parent container.- Returns:
- the type of the next Ion value (never
IonType.DATAGRAM
), ornull
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 callnext()
to move onto the first child value (or learn that there's not one).Stepping into a null container (
null.list
,null.sexp
, ornull.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 callnext()
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 tostepIn()
.
-
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 anIntegerSize
representing the smallest-possible Java type of the Ionint
at the current value. If the current value isnull.int
or is not an Ionint
, 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* throwUnknownSymbolException
from this method if any annotation contains unknown text. Alternatively, implementations may provide an Iterator that throwsUnknownSymbolException
only when the user navigates the iterator to an annotation with unknown text.- Returns:
- not null.
-
getFieldId
@Deprecated int getFieldId()
Deprecated.UsegetFieldNameSymbol()
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'sSymbolToken.getText()
will be null. If the symbol ID of the token isn't known, the result'sSymbolToken.getSid()
will beSymbolTable.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
ornull.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 whengetType()
returnsIonType.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 aBigInteger
. 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 aBigDecimal
. This method should not return aDecimal
, so it lacks support for negative zeros.This method is only valid when
getType()
returnsIonType.DECIMAL
.- Returns:
- the current value as a
BigDecimal
, ornull
if the current value isnull.decimal
.
-
decimalValue
Decimal decimalValue()
Returns the current value as aDecimal
, which extendsBigDecimal
with support for negative zeros. This is only valid whengetType()
returnsIonType.DECIMAL
.- Returns:
- the current value as a
Decimal
, ornull
if the current value isnull.decimal
.
-
dateValue
java.util.Date dateValue()
- Returns:
- the current value as a
Date
, ornull
if the current value isnull.timestamp
.
-
timestampValue
Timestamp timestampValue()
Returns the current value as aTimestamp
. This is only valid whengetType()
returnsIonType.TIMESTAMP
.- Returns:
- the current value as a
Timestamp
, ornull
if the current value isnull.timestamp
.
-
stringValue
java.lang.String stringValue()
Returns the current value as a Java String. This is only valid whengetType()
returnsIonType.STRING
orIonType.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 whengetType()
returnsIonType.SYMBOL
.- Returns:
- null if
isNullValue()
-
byteSize
int byteSize()
Gets the size in bytes of the current lob value. This is only valid whengetType()
returnsIonType.BLOB
orIonType.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 whengetType()
returnsIonType.BLOB
orIonType.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 whengetType()
returnsIonType.BLOB
orIonType.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.
-
-