Interface IonReader

src/main/java/com/amazon/ion/IonReader.java:143–517

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

 * This facet is supported by all readers of Ion text data.
 */
public interface IonReader
    extends Closeable, Faceted
{

    /**
     * Determines whether there is another value at the current depth;
     * in other words whether there is a sibling value that may be reached
     * using {@link #next()}.
     * This method may be
     * called multiple times, which does not move the current position.
     * <p>
     * <b>WARNING:</b> 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 {@code hasNext()} is {@link #next()}!
     *
     * @deprecated Applications should detect the end of the current level by
     * checking for a {@code null} response from {@link #next()}.
     */
    @Deprecated
    public boolean hasNext();

    /**
     * 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 {@code *Value()} methods.
     * <p>
     * A sequence of {@code next()} calls traverses the data at a constant
     * depth, within the same container.
     * Use {@link #stepIn()} to traverse down into any containers, and
     * {@link #stepOut()} to traverse up to the parent container.
     *
     * @return the type of the next Ion value (never {@link IonType#DATAGRAM}),
     * or {@code null} when there are no more elements at the current depth in
     * the same container.
     */
    public IonType next();


    /**
     * 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 {@link #next()} to move onto the first
     * child value (or learn that there's not one).
     * <p>
     * Stepping into a null container ({@code null.list}, {@code null.sexp},
     * or {@code null.struct}) behaves as if the container were empty
     * ({@code []}, {@code ()}, or <code>{}</code>).
     * <p>
     * At any time {@link #stepOut()} may be called to move the cursor back to
     * (just after) the parent value, even if there's more children remaining.
     *
     * @throws IllegalStateException if the current value isn't an Ion container.
     */
    public void stepIn();

    /**
     * Positions the iterator after the current parent's value, moving up one