Package com.amazon.ion.system

Class IonReaderBuilder

  • Direct Known Subclasses:
    _Private_IonReaderBuilder
    public abstract class IonReaderBuilder
extends java.lang.Object
    Build a new IonReader from the given IonCatalog and data source. A data source is required, while an IonCatalog is optional. If no IonCatalog is provided, an empty SimpleCatalog will be used.

    IonReaders parse incrementally, so syntax errors in the input data will not be detected as side effects of any of the build methods in this class.

    • Constructor Detail

      • IonReaderBuilder

        protected IonReaderBuilder()

    • Method Detail

      • standard

        public static IonReaderBuilder standard()
        The standard builder of IonReaders, with all configuration properties having their default values.
        Returns:
        a new, mutable builder instance.

      • copy

        public IonReaderBuilder copy()
        Creates a mutable copy of this builder.
        Returns:
        a new builder with the same configuration as this.

      • immutable

        public IonReaderBuilder immutable()
        Returns an immutable builder configured exactly like this one.
        Returns:
        this builder instance, if immutable; otherwise an immutable copy of this builder.

      • mutable

        public IonReaderBuilder mutable()
        Returns a mutable builder configured exactly like this one.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.

      • mutationCheck

        protected void mutationCheck()
        NOT FOR APPLICATION USE!

      • setCatalog

        public void setCatalog​(IonCatalog catalog)
        Sets the catalog to use when building an IonReader.
        Parameters:
        catalog - the catalog to use in built readers. If null, a new SimpleCatalog will be used.
        Throws:
        java.lang.UnsupportedOperationException - if this builder is immutable.
        See Also:
        getCatalog(), withCatalog(IonCatalog)

      • validateCatalog

        protected IonCatalog validateCatalog()

      • withIncrementalReadingEnabled

        public IonReaderBuilder withIncrementalReadingEnabled​(boolean isEnabled)

        Determines whether the IonReader will allow incremental reading of binary Ion data. When enabled, if IonReader.next() returns null at the top-level, it indicates that there is not enough data in the stream to complete a top-level value. The user may wait for more data to become available in the stream and call IonReader.next() again to continue reading. Unlike the non-incremental reader, the incremental reader will never throw an exception due to unexpected EOF during next(). If, however, Closeable.close() is called when an incomplete value is buffered, an IonException will be raised.

        There is currently no incremental text IonReader, so for text data a non-incremental IonReader will be returned regardless of the value of this option. If incremental text reading is supported in the future, it may be enabled via this option.

        When this option is enabled, auto-detection of GZIP data is not supported; the byte array or InputStream implementation provided to build(byte[]) or build(InputStream) must return uncompressed bytes. This can be achieved by wrapping the data in a GZIPInputStream and passing it to build(InputStream).

        Additionally, when this option is enabled, annotation iterators are reused by default, improving performance. See withAnnotationIteratorReuseEnabled(boolean) for more information and to disable that option.

        Although the incremental binary IonReader provides performance superior to the non-incremental binary IonReader for both incremental and non-incremental use cases, there is one caveat: the incremental implementation must be able to buffer an entire top-level value and any preceding system values (Ion version marker(s) and symbol table(s)) in memory. This will not be a problem for the vast majority of Ion streams, as it is rare for a single top-level value or symbol table to exceed a few megabytes in size. However, if the size of the stream's values risk exceeding the available memory, then this option must not be enabled.

        Parameters:
        isEnabled - true if the option is enabled; otherwise, false.
        Returns:
        this builder instance, if mutable; otherwise a mutable copy of this builder.
        See Also:
        setIncrementalReadingEnabled(), setIncrementalReadingDisabled()

      • isIncrementalReadingEnabled

        public boolean isIncrementalReadingEnabled()
        Returns:
        true if incremental reading is enabled; otherwise, false.
        See Also:
        withIncrementalReadingEnabled(boolean)

      • withAnnotationIteratorReuseEnabled

        public IonReaderBuilder withAnnotationIteratorReuseEnabled​(boolean isEnabled)

        Determines whether readers will reuse the annotation iterator returned by IonReader.iterateTypeAnnotations(). When enabled, the returned iterator remains valid only while the reader remains positioned at the current value; storing the iterator and iterating its values after that will cause undefined behavior. This provides improved performance and memory efficiency when frequently iterating annotations. When disabled, the returned iterator may be stored and used to retrieve the annotations that were on the value at the reader's position at the time of the call, regardless of where the reader is currently positioned.

        Currently, this option only has an effect when incremental reading is enabled (see withIncrementalReadingEnabled(boolean)). In that case, it is enabled by default. Non-incremental readers always act as if this option were disabled.

        Parameters:
        isEnabled - true if the option is enabled; otherwise, false.
        Returns:
        this builder instance, if mutable; otherwise a mutable copy of this builder.
        See Also:
        setAnnotationIteratorReuseEnabled(), setAnnotationIteratorReuseDisabled()

      • build

        public IonReader build​(byte[] ionData)
        Based on the builder's configuration properties, creates a new IonReader instance over the given block of Ion data, detecting whether it's text or binary data.

        This method will auto-detect and uncompress GZIPped Ion data.

        Parameters:
        ionData - the source of the Ion data, which may be either Ion binary data or UTF-8 Ion text. The reader retains a reference to the array, so its data must not be modified while the reader is active. Must not be null.
        Returns:
        a new IonReader instance; not null.
        See Also:
        IonSystem.newReader(byte[])

      • build

        public abstract IonReader build​(byte[] ionData,
                                int offset,
                                int length)
        Based on the builder's configuration properties, creates a new IonReader instance over the given block of Ion data, detecting whether it's text or binary data.

        This method will auto-detect and uncompress GZIPped Ion data.

        Parameters:
        ionData - the source of the Ion data, which is used only within the range of bytes starting at offset for len bytes. The data in that range may be either Ion binary data or UTF-8 Ion text. The reader retains a reference to the array, so its data must not be modified while the reader is active. Must not be null.
        offset - must be non-negative and less than ionData.length.
        length - must be non-negative and offset+length must not exceed ionData.length.
        See Also:
        IonSystem.newReader(byte[], int, int)

      • build

        public abstract IonReader build​(java.io.InputStream ionData)
        Based on the builder's configuration properties, creates a new IonReader instance over the given stream of Ion data, detecting whether it's text or binary data.

        This method will auto-detect and uncompress GZIPped Ion data.

        Because this library performs its own buffering, it's recommended that users avoid adding additional buffering to the given stream.

        Parameters:
        ionData - the source of the Ion data, which may be either Ion binary data or UTF-8 Ion text. Must not be null.
        Returns:
        a new reader instance. Callers must call Closeable.close() when finished with it.
        Throws:
        IonException - if the source throws IOException.
        See Also:
        IonSystem.newReader(InputStream)

      • build

        public abstract IonReader build​(java.io.Reader ionText)
        Based on the builder's configuration properties, creates a new IonReader instance over Ion text data.

        Applications should generally use build(InputStream) whenever possible, since this library has much faster Unicode decoding than the Java IO framework.

        Because this library performs its own buffering, it's recommended that you avoid adding additional buffering to the given stream.

        Parameters:
        ionText - the source of the Ion text data. Must not be null.
        Throws:
        IonException - if the source throws IOException.
        See Also:
        IonSystem.newReader(Reader)

      • build

        public abstract IonReader build​(IonValue value)
        Based on the builder's configuration properties, creates a new IonReader instance over an IonValue data model. Typically this is used to iterate over a collection, such as an IonStruct. The given value and its children, if any, must not be modified until after the IonReader constructed by this method is closed. Violating this constraint results in undefined behavior.
        Parameters:
        value - must not be null.
        See Also:
        IonSystem.newReader(IonValue)

      • build

        public abstract IonTextReader build​(java.lang.String ionText)
        Based on the builder's configuration properties, creates an new IonReader instance over Ion text data.
        Parameters:
        ionText - the source of the Ion text data. Must not be null.
        See Also:
        IonSystem.newReader(String)