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.

Obtaining and Usage

An IonReaderBuilder with the default configuration may be constructed as follows. This builder will construct IonReader instances which can read both text and binary Ion data and is appropriate for simple use cases or when no IonCatalog is in use. 
IonReaderBuilder readerBuilder = IonReaderBuilder.standard();
IonReaderBuilders can be configured by chaining calls to with*() configuration methods. Below is an example of a builder configured to incrementally read Ion binary data, use a custom initial buffer size, throw on inputs that would require a buffer over a specified size, and use a user-provided IonCatalog. 
// Create an IonCatalog and IonBufferConfiguration to use with IonReaderBuilder
final IonCatalog catalog = new SimpleCatalog();
final IonBufferConfiguration bufferConfiguration = IonBufferConfiguration.Builder.standard()
      .onOversizedSymbolTable(() -> { throw new IllegalStateException("Oversized system table encountered"); })
      .onOversizedValue(() -> { throw new IllegalStateException("Oversized value encountered"); })
      .withInitialBufferSize(1024)
      .withMaximumBufferSize(1024 * 1024)
      .build();

IonReaderBuilder readerBuilder = IonReaderBuilder.standard()
    .withIncrementalReadingEnabled(true)
    .withBufferConfiguration(bufferConfiguration)
    .withCatalog(catalog);

Building a Reader over a Data Source

An IonReader may be obtained from a builder by calling build over the appropriate data source. Below is an example of a reader being constructed over a string containing Ion text from a builder with the default configuration. 
IonReaderBuilder readerBuilder = IonReaderBuilder.standard();
final String helloWorld = "{hello: \"world\"}";
try (final IonReader reader = readerBuilder.build(helloWorld)) {
    reader.next();
    reader.stepIn();
    reader.next();
    System.out.println(reader.getFieldName() + " " + reader.stringValue());  // prints "hello world"
}
Builders can build an IonReader over a string, byte[] array, InputStream, Reader, or existing IonValue data model. Building a reader over a byte array allows specifying the start index and length of the data to be read. Readers built over byte[] arrays or InputStreams are capable of reading both binary and text Ion; readers built over strings and Reader instances are only capable of reading text Ion.

  • 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, IonReader.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:

    • addInputStreamInterceptor

      public IonReaderBuilder addInputStreamInterceptor(InputStreamInterceptor streamInterceptor)
      Adds an InputStreamInterceptor to the end of the list that the builder will attempt to apply to a stream before creating IonReader instances over that stream. GzipStreamInterceptor is normally consulted first, and need not be added. The first interceptor in the list that matches the stream will be used; if any chaining of interceptors is required, it is up to the caller to provide a custom interceptor implementation to achieve this.

      Users may also or instead register implementations as service providers on the classpath. See ServiceLoader for details about how to do this.

      The list of stream interceptors available to the reader normally begins with GzipStreamInterceptor and is followed by:

      1. any stream interceptors detected on the classpath using ServiceLoader.load(Class), then
      2. any stream interceptor(s) added by calling this method.
      If GZIP auto-decompression has been disabled via withGzipDecompressionEnabled(boolean), GzipStreamInterceptor is omitted from the list and any GzipStreamInterceptor added by calling this method is filtered out.
      Parameters:
      streamInterceptor - the stream interceptor to add.
      Returns:
      this builder instance, if mutable; otherwise a mutable copy of this builder.

    • getInputStreamInterceptors

      public List<InputStreamInterceptor> getInputStreamInterceptors()
      Gets the InputStreamInterceptor instances available to this builder. Unless GZIP auto-decompression has been disabled via withGzipDecompressionEnabled(boolean), the returned list will begin with the default stream interceptor, which detects GZIP. Any stream interceptor(s) detected on the classpath by ServiceLoader.load(Class) will immediately follow. Any stream interceptor(s) manually added using addInputStreamInterceptor(InputStreamInterceptor) will occur at the end of the list. If GZIP auto-decompression has been disabled, GzipStreamInterceptor is omitted from the returned list.
      Returns:
      an unmodifiable view of the stream interceptors currently configured.

    • withGzipDecompressionEnabled

      public IonReaderBuilder withGzipDecompressionEnabled(boolean enabled)
      Declares whether GZIP auto-decompression is enabled when building an IonReader, returning a new mutable builder if the current one is immutable. When enabled (the default), GZIP-compressed Ion data is automatically detected and decompressed. When disabled, GZIP-compressed data is not auto-decompressed.
      Parameters:
      enabled - true to enable GZIP auto-decompression (default), false to disable.
      Returns:
      this builder instance, if mutable; otherwise a mutable copy of this builder.

    • setGzipDecompressionEnabled

      public void setGzipDecompressionEnabled(boolean enabled)
      Sets whether GZIP auto-decompression is enabled.
      Parameters:
      enabled - true to enable GZIP auto-decompression (default), false to disable.
      Throws:
      UnsupportedOperationException - if this builder is immutable.
      See Also:

    • isGzipDecompressionEnabled

      public boolean isGzipDecompressionEnabled()
      Returns:
      true if GZIP auto-decompression is enabled (the default).

    • 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, unless GZIP auto-decompression has been disabled via withGzipDecompressionEnabled(boolean).

      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, unless GZIP auto-decompression has been disabled via withGzipDecompressionEnabled(boolean).

      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, unless GZIP auto-decompression has been disabled via withGzipDecompressionEnabled(boolean).

      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 IonReader.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: