com.amazon.ion.system

Class IonSystemBuilder

java.lang.Object

com.amazon.ion.system.IonSystemBuilder

public class IonSystemBuilder
extends java.lang.Object

The builder for creating IonSystems. Most applications will only have one or two system instances; see IonSystem for important constraints.

Builders may be configured once and reused to construct multiple objects. They can be copied to create a mutable copy of a prototype (presumably for altering some property).

Instances of this class are not safe for use by multiple threads unless they are immutable.

The easiest way to get going is to use the standard() builder:

    IonSystem ion = IonSystemBuilder.standard().build();

However, most long-lived applications will want to provide a custom IonCatalog implementation rather than using the default SimpleCatalog. For example:

    IonCatalog catalog = newCustomCatalog();
    IonSystemBuilder b = IonSystemBuilder.standard().copy();
    b.setCatalog(catalog);
    IonSystem ion = b.build();

Configuration properties follow the standard JavaBeans idiom in order to be friendly to dependency injection systems. They also provide alternative mutation methods that enable a more fluid style:

    IonCatalog catalog = newCustomCatalog();
    IonSystem ion = IonSystemBuilder.standard()
                                    .withCatalog(catalog)
                                    .build();

Configuration Properties

This builder provides the following configurable properties:

• catalog: The IonCatalog used as a default when reading Ion data. If null, each system will be built with a new SimpleCatalog.
• streamCopyOptimized: When true, this enables optimizations when copying data between two Ion streams. For example, in some cases raw binary-encoded Ion can be copied directly from the input to the output. This can have significant performance benefits when the appropriate conditions are met. This feature is experimental! Please test thoroughly and report any issues.

Method Summary

Modifier and Type	Method and Description
IonSystem	build() Builds a new IonSystem instance based on this builder's configuration properties.
IonSystemBuilder	copy() Creates a mutable copy of this builder.
IonCatalog	getCatalog() Gets the catalog to use when building an IonSystem.
IonBinaryWriterBuilder	getIonBinaryWriterBuilder() Gets the binary writer builder whose options will be used when building an IonSystem.
IonTextWriterBuilder	getIonTextWriterBuilder() Gets the text writer builder whose options will be used when building an IonSystem.
IonReaderBuilder	getReaderBuilder() Gets the reader builder whose options will be used when building an IonSystem.
IonSystemBuilder	immutable() Returns an immutable builder configured exactly like this one.
boolean	isStreamCopyOptimized() Indicates whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data.
IonSystemBuilder	mutable() Returns a mutable builder configured exactly like this one.
void	setCatalog(IonCatalog catalog) Sets the catalog to use when building an IonSystem.
void	setIonBinaryWriterBuilder(IonBinaryWriterBuilder builder) Sets the binary writer builder whose options will be used when building an IonSystem.
void	setIonTextWriterBuilder(IonTextWriterBuilder builder) Sets the text writer builder whose options will be used when building an IonSystem.
void	setReaderBuilder(IonReaderBuilder builder) Sets the reader builder whose options will be used to use when building an IonSystem.
void	setStreamCopyOptimized(boolean optimized) Declares whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data.
static IonSystemBuilder	standard() The standard builder of IonSystems.
IonSystemBuilder	withCatalog(IonCatalog catalog) Declares the catalog to use when building an IonSystem, returning a new mutable builder if this is immutable.
IonSystemBuilder	withIonBinaryWriterBuilder(IonBinaryWriterBuilder builder) Declares the binary writer builder whose options will be used to use when building an IonSystem, returning a new mutable builder if this is immutable.
IonSystemBuilder	withIonTextWriterBuilder(IonTextWriterBuilder builder) Declares the text writer builder whose options will be used when building an IonSystem, returning a new mutable builder if this is immutable.
IonSystemBuilder	withReaderBuilder(IonReaderBuilder builder) Declares the reader builder whose options will be used to use when building an IonSystem, returning a new mutable builder if this is immutable.
IonSystemBuilder	withStreamCopyOptimized(boolean optimized) Declares whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data, returning a new mutable builder if this 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 IonSystemBuilder standard()

The standard builder of IonSystems. See the class documentation for the standard configuration.

The returned instance is immutable.

copy

public final IonSystemBuilder copy()

Creates a mutable copy of this builder.

Returns:

a new builder with the same configuration as this.

immutable

public IonSystemBuilder immutable()

Returns an immutable builder configured exactly like this one.

Returns:

this instance, if immutable; otherwise an immutable copy of this instance.

mutable

public IonSystemBuilder mutable()

Returns a mutable builder configured exactly like this one.

Returns:

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

getCatalog

public final IonCatalog getCatalog()

Gets the catalog to use when building an IonSystem. By default, this property is null.

See Also:

setCatalog(IonCatalog), withCatalog(IonCatalog), IonSystem.getCatalog()

setCatalog

public final void setCatalog(IonCatalog catalog)

Sets the catalog to use when building an IonSystem.

Parameters:

catalog - the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.

Throws:

java.lang.UnsupportedOperationException - if this is immutable.

See Also:

getCatalog(), withCatalog(IonCatalog), IonSystem.getCatalog()

withCatalog

public final IonSystemBuilder withCatalog(IonCatalog catalog)

Declares the catalog to use when building an IonSystem, returning a new mutable builder if this is immutable.

Parameters:

catalog - the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.

See Also:

getCatalog(), setCatalog(IonCatalog), IonSystem.getCatalog()

isStreamCopyOptimized

public final boolean isStreamCopyOptimized()

Indicates whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data. By default, this property is false.

See Also:

setStreamCopyOptimized(boolean), withStreamCopyOptimized(boolean)

setStreamCopyOptimized

public final void setStreamCopyOptimized(boolean optimized)

Declares whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data. By default, this property is false.

This feature is experimental! Please test thoroughly and report any issues.

Throws:

java.lang.UnsupportedOperationException - if this is immutable.

See Also:

isStreamCopyOptimized(), withStreamCopyOptimized(boolean)

withStreamCopyOptimized

public final IonSystemBuilder withStreamCopyOptimized(boolean optimized)

Declares whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data, returning a new mutable builder if this is immutable.

This feature is experimental! Please test thoroughly and report any issues.

See Also:

isStreamCopyOptimized(), setStreamCopyOptimized(boolean)

getIonTextWriterBuilder

public final IonTextWriterBuilder getIonTextWriterBuilder()

Gets the text writer builder whose options will be used when building an IonSystem. By default, IonTextWriterBuilder.standard() using US-ASCII encoding will be used.

See Also:

setIonTextWriterBuilder(IonTextWriterBuilder), withIonTextWriterBuilder(IonTextWriterBuilder)

setIonTextWriterBuilder

public final void setIonTextWriterBuilder(IonTextWriterBuilder builder)

Sets the text writer builder whose options will be used when building an IonSystem.

Parameters:

builder - the writer builder to use in built systems. If unset, each system will be built with IonTextWriterBuilder.standard() using US-ASCII encoding.

Throws:

java.lang.UnsupportedOperationException - if this is immutable.

See Also:

getIonTextWriterBuilder(), withIonTextWriterBuilder(IonTextWriterBuilder)

withIonTextWriterBuilder

public final IonSystemBuilder withIonTextWriterBuilder(IonTextWriterBuilder builder)

Declares the text writer builder whose options will be used when building an IonSystem, returning a new mutable builder if this is immutable. The writer builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.

Parameters:

builder - the writer builder to use in built systems. If unset, each system will be built with IonTextWriterBuilder.standard() using US-ASCII encoding.

See Also:

getIonTextWriterBuilder(), setIonTextWriterBuilder(IonTextWriterBuilder)

getIonBinaryWriterBuilder

public final IonBinaryWriterBuilder getIonBinaryWriterBuilder()

Gets the binary writer builder whose options will be used when building an IonSystem. By default, IonBinaryWriterBuilder.standard() will be used.

See Also:

setIonBinaryWriterBuilder(IonBinaryWriterBuilder), withIonBinaryWriterBuilder(IonBinaryWriterBuilder)

setIonBinaryWriterBuilder

public final void setIonBinaryWriterBuilder(IonBinaryWriterBuilder builder)

Sets the binary writer builder whose options will be used when building an IonSystem. The writer builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.

Parameters:

builder - the writer builder to use in built systems. If unset, each system will be built with IonBinaryWriterBuilder.standard().

Throws:

java.lang.UnsupportedOperationException - if this is immutable.

See Also:

getIonBinaryWriterBuilder(), withIonBinaryWriterBuilder(IonBinaryWriterBuilder)

withIonBinaryWriterBuilder

public final IonSystemBuilder withIonBinaryWriterBuilder(IonBinaryWriterBuilder builder)

Declares the binary writer builder whose options will be used to use when building an IonSystem, returning a new mutable builder if this is immutable. The writer builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.

Parameters:

builder - the writer builder to use in built systems. If unset, each system will be built with IonBinaryWriterBuilder.standard().

See Also:

getIonBinaryWriterBuilder(), setIonBinaryWriterBuilder(IonBinaryWriterBuilder)

getReaderBuilder

public final IonReaderBuilder getReaderBuilder()

Gets the reader builder whose options will be used when building an IonSystem. By default, IonReaderBuilder.standard() will be used.

See Also:

setReaderBuilder(IonReaderBuilder), withReaderBuilder(IonReaderBuilder)

setReaderBuilder

public final void setReaderBuilder(IonReaderBuilder builder)

Sets the reader builder whose options will be used to use when building an IonSystem. The reader builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.

Parameters:

builder - the reader builder to use in built systems. If unset, each system will be built with IonReaderBuilder.standard().

Throws:

java.lang.UnsupportedOperationException - if this is immutable.

See Also:

getReaderBuilder(), withReaderBuilder(IonReaderBuilder)

withReaderBuilder

public final IonSystemBuilder withReaderBuilder(IonReaderBuilder builder)

Declares the reader builder whose options will be used to use when building an IonSystem, returning a new mutable builder if this is immutable. The reader builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.

Parameters:

builder - the reader builder to use in built systems. If unset, each system will be built with IonReaderBuilder.standard().

See Also:

getReaderBuilder(), setReaderBuilder(IonReaderBuilder)

build

public final IonSystem build()

Builds a new IonSystem instance based on this builder's configuration properties.