com.amazon.ion.SeekableReader Maven / Gradle / Ivy
Show all versions of ion-java Show documentation
/*
* 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.
*
* WARNING: This interface should not be implemented or extended by
* code outside of this library.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
*/
// public void start(Span span); // TODO later
}