software.amazon.ion.system

Class IonReaderBuilder

java.lang.Object

software.amazon.ion.system.IonReaderBuilder

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

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.
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.
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.
IonReader	build(IonValue value) Based on the builder's configuration properties, creates a new IonReader instance over an IonValue data model.
IonReader	build(Reader ionText) Based on the builder's configuration properties, creates a new IonReader instance over Ion text data.
IonReader	build(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.
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.
IonReaderBuilder	mutable() Returns a mutable builder configured exactly like this one.
protected void	mutationCheck() NOT FOR APPLICATION USE!
void	setCatalog(IonCatalog catalog) Sets the catalog to use when building an IonReader.
static IonReaderBuilder	standard() The standard builder of IonReaders, with all configuration properties having their default values.
IonReaderBuilder	withCatalog(IonCatalog catalog) Declares the catalog to use when building an IonReader, returning a new mutable builder the current one is immutable.

Methods inherited from class java.lang.Object

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

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:

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)

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

IonSystem.newReader(InputStream)

build

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

IonSystem.newReader(Reader)

build

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

Parameters:

value - must not be null.

See Also:

IonSystem.newReader(IonValue)

build

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

IonSystem.newReader(String)