src/com/amazon/ion/SeekableReader.java

/*
 * Copyright 2007-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * or in the "license" file accompanying this file. This file is distributed
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 * express or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

package com.amazon.ion;

/**
 * An {@link IonReader} facet providing the ability to retrieve
 * {@link Span}s (abstract value positions) and seek to positions
 * within the source.
 * <p>
 * <b>WARNING:</b> This interface should not be implemented or extended by
 * code outside of this library.
 * <p>
 * A span may be used to seek a different reader instance than the one that
 * generated it, provided that the two readers have the same source.
 * Violations of this constraint may not be detected reliably, so be careful
 * or you'll get unsatisfying results.
 *
 */
public interface SeekableReader
    extends SpanProvider
{
    /**
     * Seeks this reader to produce the given span as if its values were at
     * top-level.
     * The caller cannot {@link IonReader#stepOut stepOut} from the span nor
     * continue reading beyond it.
     * <p>
     * After calling this method, this reader's current span will be empty and
     * positioned just before the first value of the given span; the caller
     * must call {@link IonReader#next() next()} to begin reading values.
     * At the end of the span, the reader will behave as if it's at EOF
     * regardless whether the source has more data beyond the span.
     * <p>
     * Hoisting makes the span's values appear to be at top-level even if they
     * have containers in the source.
     * The {@linkplain IonReader#getDepth() depth} will be zero, and
     * calls to {@link IonReader#getFieldName() getFieldName()} will return
     * null even if the span's original parent was a struct.
     *
     * @throws IonException if the given span is unbalanced.
     */
    public void hoist(Span span);


    /**
     * Seeks this reader to produce the given subsequence as if the values
     * were the body of a container.
     * The caller can {@link IonReader#stepOut stepOut} from the subsequence
     * but cannot continue reading beyond it.
     * <p>
     * After calling this method, this reader's current span will be empty and
     * positioned just before the first value of the given span; the caller
     * must call {@link #next()} to begin reading values.
     * The {@linkplain #getDepth() depth} will be one.
     * <p>
     * If the original parent was a struct, then this reader will implement
     * {@link #isInStruct()} and {@link #getFieldName()}.
     *
     * @throws IonException if the given span is unbalanced or at top-level.
     */
//  public void stepIn(Span span);


    /**
     * Seeks this reader to produce data from the left of the given span,
     * continuing "up and out" from the current container to the end of the
     * source.
     * <p>
     * After calling this method, the reader's current span will be empty and
     * positioned just before the first value of the given span; the caller
     * must call {@link #next()} to begin reading values.
     * The {@linkplain #getDepth() depth} will be the same as in the source.
     * <p>
     */
//    public void start(Span span);  // TODO later
}