Ion Java 1.11.10 · com.amazon.ion.system.IonReaderBuilder

Modifier and Type	Field and Description
private IonBufferConfiguration	bufferConfiguration
private IonCatalog	catalog
private static final List<InputStreamInterceptor>	DEFAULT_STREAM_INTERCEPTORS
private static final List<InputStreamInterceptor>	DETECTED_STREAM_INTERCEPTORS
private boolean	isIncrementalReadingEnabled
private List<InputStreamInterceptor>	streamInterceptors

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

Method Summary

Modifier and Type	Method and Description
public IonReaderBuilder	Returns: this builder instance, if mutable; otherwise a mutable copy of this builder. addInputStreamInterceptor(InputStreamInterceptor the stream interceptor to add. 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.
public IonReader	Returns: a new `IonReader` instance; not `null`. build(byte[] 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. 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.
public abstract IonReader	build(byte[] 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. ionData, int must be non-negative and less than `ionData.length`. offset, int must be non-negative and `offset+length` must not exceed `ionData.length`. 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.
public abstract IonReader	Returns: a new reader instance. Callers must call `IonReader#close()` when finished with it. build(InputStream the source of the Ion data, which may be either Ion binary data or UTF-8 Ion text. Must not be null. 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.
public abstract IonReader	build(Reader the source of the Ion text data. Must not be null. ionText) Based on the builder's configuration properties, creates a new `IonReader` instance over Ion text data.
public abstract IonReader	build(IonValue must not be null. value) Based on the builder's configuration properties, creates a new `IonReader` instance over an `IonValue` data model.
public abstract IonTextReader	build(String the source of the Ion text data. Must not be null. ionText) References Deprecated `IonTextReader` is deprecated or references (maybe indirectly) at least one deprecated element. Based on the builder's configuration properties, creates an new `IonReader` instance over Ion text data.
public IonReaderBuilder	Returns: a new builder with the same configuration as `this`. copy() Creates a mutable copy of this builder.
private static List<InputStreamInterceptor>	Returns: the stream interceptors. detectStreamInterceptorsOnClasspath() Detects implementations of `InputStreamInterceptor` available to the `ClassLoader` that loaded this class, appending any implementations found to the list of stream interceptors enabled by default.
public IonBufferConfiguration	Returns: the current configuration. getBufferConfiguration()
public IonCatalog	getCatalog() Gets the catalog to use when building an `IonReader`, or null if none has been manually set.
public List<InputStreamInterceptor>	Returns: an unmodifiable view of the stream interceptors currently configured. getInputStreamInterceptors() Gets the `InputStreamInterceptor` instances available to this builder.
public IonReaderBuilder	Returns: this builder instance, if immutable; otherwise an immutable copy of this builder. immutable() Returns an immutable builder configured exactly like this one.
public boolean	Returns: true if incremental reading is enabled; otherwise, false. isIncrementalReadingEnabled()
public IonReaderBuilder	Returns: this instance, if mutable; otherwise a mutable copy of this instance. mutable() Returns a mutable builder configured exactly like this one.
protected void	mutationCheck() NOT FOR APPLICATION USE!
public void	setBufferConfiguration(IonBufferConfiguration configuration)
public void	setCatalog(IonCatalog the catalog to use in built readers. If null, a new `SimpleCatalog` will be used. catalog) Sets the catalog to use when building an `IonReader`.
public void	setIncrementalReadingDisabled()
public void	setIncrementalReadingEnabled()
public static IonReaderBuilder	Returns: a new, mutable builder instance. standard() The standard builder of `IonReader`s, with all configuration properties having their default values.
protected IonCatalog	validateCatalog()
public IonReaderBuilder	Returns: this builder instance, if mutable; otherwise a mutable copy of this builder. withBufferConfiguration(IonBufferConfiguration the configuration. configuration) Sets the buffer configuration.
public IonReaderBuilder	Returns: this builder instance, if mutable; otherwise a mutable copy of this builder. withCatalog(IonCatalog the catalog to use in built readers. If null, a new `SimpleCatalog` will be used. catalog) Declares the catalog to use when building an `IonReader`, returning a new mutable builder the current one is immutable.
public IonReaderBuilder	Returns: this builder instance, if mutable; otherwise a mutable copy of this builder. withIncrementalReadingEnabled(boolean true if the option is enabled; otherwise, false. isEnabled) Determines whether the IonReader will allow incremental reading of binary Ion data.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

bufferConfiguration	back to summary
private IonBufferConfiguration bufferConfiguration

catalog	back to summary
private IonCatalog catalog

DEFAULT_STREAM_INTERCEPTORS	back to summary
private static final List<InputStreamInterceptor> DEFAULT_STREAM_INTERCEPTORS

DETECTED_STREAM_INTERCEPTORS	back to summary
private static final List<InputStreamInterceptor> DETECTED_STREAM_INTERCEPTORS

isIncrementalReadingEnabled	back to summary
private boolean isIncrementalReadingEnabled

streamInterceptors	back to summary
private List<InputStreamInterceptor> streamInterceptors

IonReaderBuilder	back to summary
protected IonReaderBuilder()

IonReaderBuilder	back to summary
protected IonReaderBuilder(IonReaderBuilder that)

Method Detail

addInputStreamInterceptor back to summary

addInputStreamInterceptor	back to summary
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 always 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 always begins with `GzipStreamInterceptor` and is followed by: any stream interceptors detected on the classpath using `ServiceLoader#load(Class)`, then any stream interceptor(s) added by calling this method. Parameters streamInterceptor:InputStreamInterceptor the stream interceptor to add. Returns:IonReaderBuilder this builder instance, if mutable; otherwise a mutable copy of this builder.

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 always 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 always begins with GzipStreamInterceptor and is followed by:

any stream interceptors detected on the classpath using ServiceLoader#load(Class), then
any stream interceptor(s) added by calling this method.

Parameters

streamInterceptor:InputStreamInterceptor: the stream interceptor to add.

Returns:IonReaderBuilder

this builder instance, if mutable; otherwise a mutable copy of this builder.

build back to summary

build	back to summary
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:byte[] 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:IonReader a new `IonReader` instance; not `null`. See Also `IonSystem#newReader(byte[])`

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:byte[]: 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:IonReader

a new IonReader instance; not null.

See Also

IonSystem#newReader(byte[])

build back to summary

build	back to summary
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:byte[] 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:int must be non-negative and less than `ionData.length`. length:int must be non-negative and `offset+length` must not exceed `ionData.length`. See Also `IonSystem#newReader(byte[], int, int)`

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:byte[]: 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:int: must be non-negative and less than ionData.length.
length:int: must be non-negative and offset+length must not exceed ionData.length.

See Also

IonSystem#newReader(byte[], int, int)

build back to summary

build	back to summary
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:InputStream the source of the Ion data, which may be either Ion binary data or UTF-8 Ion text. Must not be null. Returns:IonReader a new reader instance. Callers must call `IonReader#close()` when finished with it. Exceptions IonException: if the source throws `IOException`. See Also `IonSystem#newReader(InputStream)`

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:InputStream: the source of the Ion data, which may be either Ion binary data or UTF-8 Ion text. Must not be null.

Returns:IonReader

a new reader instance. Callers must call IonReader#close() when finished with it.

Exceptions

IonException:: if the source throws IOException.

See Also

IonSystem#newReader(InputStream)

build back to summary

build	back to summary
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:Reader the source of the Ion text data. Must not be null. Exceptions IonException: if the source throws `IOException`. See Also `IonSystem#newReader(Reader)`

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:Reader: the source of the Ion text data. Must not be null.

Exceptions

IonException:: if the source throws IOException.

See Also

IonSystem#newReader(Reader)

build back to summary

build	back to summary
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:IonValue must not be null. See Also `IonSystem#newReader(IonValue)`

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:IonValue: must not be null.

See Also

IonSystem#newReader(IonValue)

build back to summary

build	back to summary
public abstract IonTextReader build(String ionText) References Deprecated `IonTextReader` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. Based on the builder's configuration properties, creates an new `IonReader` instance over Ion text data. Parameters ionText:String the source of the Ion text data. Must not be null. See Also `IonSystem#newReader(String)`

public abstract IonTextReader build(String ionText)

References Deprecated

IonTextReader is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Based on the builder's configuration properties, creates an new IonReader instance over Ion text data.

Parameters

ionText:String: the source of the Ion text data. Must not be null.

See Also

IonSystem#newReader(String)

copy back to summary

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

public IonReaderBuilder copy()

Creates a mutable copy of this builder.

Returns:IonReaderBuilder: a new builder with the same configuration as this.

detectStreamInterceptorsOnClasspath back to summary

detectStreamInterceptorsOnClasspath	back to summary
private static List<InputStreamInterceptor> detectStreamInterceptorsOnClasspath() Detects implementations of `InputStreamInterceptor` available to the `ClassLoader` that loaded this class, appending any implementations found to the list of stream interceptors enabled by default. Returns:List<InputStreamInterceptor> the stream interceptors.

private static List<InputStreamInterceptor> detectStreamInterceptorsOnClasspath()

Detects implementations of InputStreamInterceptor available to the ClassLoader that loaded this class, appending any implementations found to the list of stream interceptors enabled by default.

Returns:List<InputStreamInterceptor>: the stream interceptors.

getBufferConfiguration	back to summary
public IonBufferConfiguration getBufferConfiguration() Returns:IonBufferConfiguration the current configuration. See Also `withBufferConfiguration(IonBufferConfiguration)`

getCatalog back to summary

getCatalog	back to summary
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)`

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)

getInputStreamInterceptors back to summary

getInputStreamInterceptors	back to summary
public List<InputStreamInterceptor> getInputStreamInterceptors() Gets the `InputStreamInterceptor` instances available to this builder. The returned list will always 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. Returns:List<InputStreamInterceptor> an unmodifiable view of the stream interceptors currently configured.

public List<InputStreamInterceptor> getInputStreamInterceptors()

Gets the InputStreamInterceptor instances available to this builder. The returned list will always 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.

Returns:List<InputStreamInterceptor>: an unmodifiable view of the stream interceptors currently configured.

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

immutable

back to summary

public IonReaderBuilder immutable()

Returns an immutable builder configured exactly like this one.

Returns:IonReaderBuilder: this builder instance, if immutable; otherwise an immutable copy of this builder.

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

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

mutable

back to summary

public IonReaderBuilder mutable()

Returns a mutable builder configured exactly like this one.

Returns:IonReaderBuilder: this instance, if mutable; otherwise a mutable copy of this instance.

mutationCheck	back to summary
protected void mutationCheck() NOT FOR APPLICATION USE!

setBufferConfiguration	back to summary
public void setBufferConfiguration(IonBufferConfiguration configuration) See Also `withBufferConfiguration(IonBufferConfiguration)`

setCatalog back to summary

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

public void setCatalog(IonCatalog catalog)

Sets the catalog to use when building an IonReader.

Parameters

catalog:IonCatalog: the catalog to use in built readers. If null, a new SimpleCatalog will be used.

Exceptions

UnsupportedOperationException:: if this builder is immutable.

setIncrementalReadingDisabled	back to summary
public void setIncrementalReadingDisabled() See Also `withIncrementalReadingEnabled(boolean)`

setIncrementalReadingEnabled	back to summary
public void setIncrementalReadingEnabled() See Also `withIncrementalReadingEnabled(boolean)`

standard back to summary

standard	back to summary
public static IonReaderBuilder standard() The standard builder of `IonReader`s, with all configuration properties having their default values. Returns:IonReaderBuilder a new, mutable builder instance.

public static IonReaderBuilder standard()

The standard builder of IonReaders, with all configuration properties having their default values.

Returns:IonReaderBuilder: a new, mutable builder instance.

validateCatalog	back to summary
protected IonCatalog validateCatalog()

withBufferConfiguration back to summary

withBufferConfiguration	back to summary
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:IonBufferConfiguration the configuration. Returns:IonReaderBuilder this builder instance, if mutable; otherwise a mutable copy of this builder. See Also `setBufferConfiguration(IonBufferConfiguration)`

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:IonBufferConfiguration: the configuration.

Returns:IonReaderBuilder

this builder instance, if mutable; otherwise a mutable copy of this builder.

withCatalog back to summary

withCatalog	back to summary
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:IonCatalog the catalog to use in built readers. If null, a new `SimpleCatalog` will be used. Returns:IonReaderBuilder this builder instance, if mutable; otherwise a mutable copy of this builder. See Also `setCatalog(IonCatalog)`, `withCatalog(IonCatalog)`

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:IonCatalog: the catalog to use in built readers. If null, a new SimpleCatalog will be used.

Returns:IonReaderBuilder

this builder instance, if mutable; otherwise a mutable copy of this builder.

withIncrementalReadingEnabled back to summary

withIncrementalReadingEnabled	back to summary
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:boolean true if the option is enabled; otherwise, false. Returns:IonReaderBuilder this builder instance, if mutable; otherwise a mutable copy of this builder. See Also `setIncrementalReadingEnabled()`, `setIncrementalReadingDisabled()`

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:boolean: true if the option is enabled; otherwise, false.

Returns:IonReaderBuilder

this builder instance, if mutable; otherwise a mutable copy of this builder.

public abstract Class IonReaderBuilder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail