com.amazon.ion

Interface IonCursor

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface IonCursor
extends java.io.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 and Description
static class	IonCursor.Event Conveys the type of event that occurred as a result of operating on the cursor.

Method Summary

Modifier and Type	Method and 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 Detail

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.