com.amazon.ion.system

Class IonReaderBuilder

java.lang.Object

com.amazon.ion.system.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 Summary

Constructors

Modifier	Constructor and Description
protected	IonReaderBuilder()
protected	IonReaderBuilder(IonReaderBuilder that)

Method Summary

Modifier and Type	Method and Description
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.
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.
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.
abstract IonReader	build(IonValue value) Based on the builder's configuration properties, creates a new IonReader instance over an IonValue data model.
abstract IonReader	build(java.io.Reader ionText) Based on the builder's configuration properties, creates a new IonReader instance over Ion text data.
abstract IonTextReader	build(java.lang.String ionText) Based on the builder's configuration properties, creates an new IonReader instance over Ion text data.
IonReaderBuilder	copy() Creates a mutable copy of this builder.
IonBufferConfiguration	getBufferConfiguration()
IonCatalog	getCatalog() Gets the catalog to use when building an IonReader, or null if none has been manually set.
IonReaderBuilder	immutable() Returns an immutable builder configured exactly like this one.
boolean	isIncrementalReadingEnabled()
IonReaderBuilder	mutable() Returns a mutable builder configured exactly like this one.
protected void	mutationCheck() NOT FOR APPLICATION USE!
void	setBufferConfiguration(IonBufferConfiguration configuration)
void	setCatalog(IonCatalog catalog) Sets the catalog to use when building an IonReader.
void	setIncrementalReadingDisabled()
void	setIncrementalReadingEnabled()
static IonReaderBuilder	standard() The standard builder of IonReaders, with all configuration properties having their default values.
protected IonCatalog	validateCatalog()
IonReaderBuilder	withBufferConfiguration(IonBufferConfiguration configuration) Sets the buffer configuration.
IonReaderBuilder	withCatalog(IonCatalog catalog) Declares the catalog to use when building an IonReader, returning a new mutable builder the current one is immutable.
IonReaderBuilder	withIncrementalReadingEnabled(boolean isEnabled) Determines whether the IonReader will allow incremental reading of binary Ion data.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IonReaderBuilder

protected IonReaderBuilder()

IonReaderBuilder

protected IonReaderBuilder(IonReaderBuilder that)

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!

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(IonCatalog), withCatalog(IonCatalog)

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)

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:

setCatalog(IonCatalog), 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.

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(), setIncrementalReadingDisabled()

setIncrementalReadingEnabled

public void setIncrementalReadingEnabled()

See Also:

withIncrementalReadingEnabled(boolean)

setIncrementalReadingDisabled

public void setIncrementalReadingDisabled()

See Also:

withIncrementalReadingEnabled(boolean)

isIncrementalReadingEnabled

public boolean isIncrementalReadingEnabled()

Returns:

true if incremental reading is enabled; otherwise, false.

See Also:

withIncrementalReadingEnabled(boolean)

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(IonBufferConfiguration)

setBufferConfiguration

public void setBufferConfiguration(IonBufferConfiguration configuration)

See Also:

withBufferConfiguration(IonBufferConfiguration)

getBufferConfiguration

public IonBufferConfiguration getBufferConfiguration()

Returns:

the current configuration.

See Also:

withBufferConfiguration(IonBufferConfiguration)

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)