Package com.amazon.ion.system

Class IonReaderBuilder

java.lang.Object
com.amazon.ion.system.IonReaderBuilder
Direct Known Subclasses:
_Private_IonReaderBuilder
public abstract class IonReaderBuilder extends 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 Details

    • IonReaderBuilder

      protected IonReaderBuilder()

    • IonReaderBuilder

      protected IonReaderBuilder(IonReaderBuilder that)

  • Method Details

    • 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!

    • withCatalog

      public IonReaderBuilder withCatalog(IonCatalog catalog)
      Declares the catalog to use when building an IonReader, returning a new mutable builder the current one is immutable.
      Parameters:
      catalog - the catalog to use in built readers. If null, a new SimpleCatalog will be used.
      Returns:
      this builder instance, if mutable; otherwise a mutable copy of this builder.
      See Also:

    • 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:
      UnsupportedOperationException - if this builder is immutable.
      See Also:

    • getCatalog

      public IonCatalog getCatalog()
      Gets the catalog to use when building an IonReader, or null if none has been manually set. The catalog is needed to resolve shared symbol table imports.
      See Also:

    • 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.

      There is one caveat to note when using this option: the incremental implementation must be able to buffer an entire top-level value 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 risks 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

      public void setIncrementalReadingEnabled()
      See Also:

    • setIncrementalReadingDisabled

      public void setIncrementalReadingDisabled()
      See Also:

    • isIncrementalReadingEnabled

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

    • withBufferConfiguration

      public IonReaderBuilder withBufferConfiguration(IonBufferConfiguration configuration)
      Sets the buffer configuration. This can be used, for example, to set a maximum buffer size and receive notifications when values would exceed this size. Currently, this is ignored unless incremental reading has been enabled via withIncrementalReadingEnabled(boolean)) or setIncrementalReadingEnabled(). This configuration is optional. If not provided, the buffer size will be limited only by the available memory.
      Parameters:
      configuration - the configuration.
      Returns:
      this builder instance, if mutable; otherwise a mutable copy of this builder.
      See Also:

    • setBufferConfiguration

      public void setBufferConfiguration(IonBufferConfiguration configuration)
      See Also:

    • getBufferConfiguration

      public IonBufferConfiguration getBufferConfiguration()
      Returns:
      the current configuration.
      See Also:

    • 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:

    • 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:

    • build

      public abstract IonReader build(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:

    • build

      public abstract IonReader build(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:

    • 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:

    • build

      public abstract IonTextReader build(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: