Package com.amazon.ion

Interface IonCursor

All Superinterfaces:
AutoCloseable, Closeable
public interface IonCursor extends Closeable
A cursor over a stream of Ion data. NOTE: this interface is not considered part of the public API.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    IonCursor.Event
    Conveys the type of event that occurred as a result of operating on the cursor.

  • Method Summary

    Modifier and Type
    Method
    Description
    IonCursor.Event
    endStream()
    Causes the cursor to force completion of the value on which it is currently positioned, if any.
    IonCursor.Event
    fillValue()
    Buffers the entirety of the value on which the cursor is currently positioned.
    IonCursor.Event
    getCurrentEvent()
    Conveys the result of the previous operation.
    IonCursor.Event
    nextValue()
    Advances the cursor to the next value, skipping the current value (if any).
    IonCursor.Event
    stepIntoContainer()
    Steps the cursor into the container value on which the cursor is currently positioned.
    IonCursor.Event
    stepOutOfContainer()
    Steps the cursor out of the current container, skipping any values in the container that may follow.

    Methods inherited from interface java.io.Closeable

    close

  • Method Details

    • nextValue

      IonCursor.Event nextValue()
      Advances the cursor to the next value, skipping the current value (if any). This method may return:
      • NEEDS_DATA, if not enough data is available in the stream
      • START_SCALAR, if the reader is now positioned on a scalar value
      • START_CONTAINER, if the reader is now positioned on a container value
      • END_CONTAINER, if the reader is now positioned at the end of a container value, or
      • NEEDS_INSTRUCTION, if the reader skipped a value for exceeding the configured maximum buffer size
      Returns:
      an Event conveying the result of the operation.

    • stepIntoContainer

      IonCursor.Event stepIntoContainer()
      Steps the cursor into the container value on which the cursor is currently positioned. This method may return:
      • NEEDS_DATA, if not enough data is available in the stream
      • NEEDS_INSTRUCTION, when successful, indicating that the caller must invoke another method on the cursor in order to position it on a value
      Returns:
      an Event conveying the result of the operation.

    • stepOutOfContainer

      IonCursor.Event stepOutOfContainer()
      Steps the cursor out of the current container, skipping any values in the container that may follow. This method may return:
      • NEEDS_DATA, if not enough data is available in the stream
      • NEEDS_INSTRUCTION, when successful, indicating that the caller must invoke another method on the cursor in order to position it on a value
      Returns:
      an Event conveying the result of the operation.

    • fillValue

      IonCursor.Event fillValue()
      Buffers the entirety of the value on which the cursor is currently positioned. This method may return:
      • NEEDS_DATA, if not enough data is available in the stream
      • VALUE_READY, if the value was successfully filled
      • NEEDS_INSTRUCTION, if the value exceeded the configured maximum buffer size and could not be buffered
      Returns:
      an Event conveying the result of the operation.

    • getCurrentEvent

      IonCursor.Event getCurrentEvent()
      Conveys the result of the previous operation.
      Returns:
      an Event conveying the result of the previous operation.

    • endStream

      IonCursor.Event endStream()
      Causes the cursor to force completion of the value on which it is currently positioned, if any. This method may return:
      • NEEDS_DATA, if called when the reader is not positioned on a value, or
      • START_SCALAR, if ending the stream at the current position unambiguously results in a complete value
      Note: in binary Ion, it is never ambiguous whether a value is complete. Therefore, binary IonCursor implementations will only return NEEDS_DATA or throw from this method. In text Ion, ambiguity is possible. For example, the stream true will initially return NEEDS_DATA from nextValue() because it cannot yet be known whether the stream contains the boolean value true or, e.g., the symbol value trueNorth. In this example, calling this method will return START_SCALAR, with the cursor positioned on a boolean value.
      Returns:
      an Event conveying the result of the operation.
      Throws:
      IonException - if this method is called below the top level or when the cursor is positioned on an incomplete value.