Top Description Inners Fields Constructors Methods
com.amazon.ion.system

public Class IonSystemBuilder

extends Object
Class Inheritance
Known Direct Subclasses
com.amazon.ion.system.IonSystemBuilder.Mutable
Static Imports
com.amazon.ion.impl.lite._Private_LiteDomTrampoline.newLiteSystem
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:

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
IonSystemBuilder.Mutable

Field Summary

Modifier and TypeField and Description
pack-priv IonBinaryWriterBuilder
binaryWriterBuilder

pack-priv IonCatalog
myCatalog

pack-priv boolean
myStreamCopyOptimized

pack-priv IonReaderBuilder
readerBuilder

private static final IonSystemBuilder
STANDARD

pack-priv IonTextWriterBuilder
textWriterBuilder

Constructor Summary

AccessConstructor and Description
private
IonSystemBuilder()

You no touchy.

private
IonSystemBuilder(IonSystemBuilder that)

Method Summary

Modifier and TypeMethod and Description
public final IonSystem
build()

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

public final IonSystemBuilder

Returns:

a new builder with the same configuration as this.
copy()

Creates a mutable copy of this builder.

public final IonCatalog
getCatalog()

Gets the catalog to use when building an IonSystem.

public final IonBinaryWriterBuilder
getIonBinaryWriterBuilder()

Gets the binary writer builder whose options will be used when building an IonSystem.

public final IonTextWriterBuilder
getIonTextWriterBuilder()

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

public final IonReaderBuilder
getReaderBuilder()

Gets the reader builder whose options will be used when building an IonSystem.

public IonSystemBuilder

Returns:

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

Returns an immutable builder configured exactly like this one.

public final boolean
isStreamCopyOptimized()

Indicates whether built systems may attempt to optimize IonWriter#writeValue(IonReader) by copying raw source data.

public IonSystemBuilder

Returns:

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

Returns a mutable builder configured exactly like this one.

pack-priv void
mutationCheck()

public final void
setCatalog(IonCatalog
the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.
catalog)

Sets the catalog to use when building an IonSystem.

public final void
setIonBinaryWriterBuilder(IonBinaryWriterBuilder
the writer builder to use in built systems. If unset, each system will be built with IonBinaryWriterBuilder#standard().
builder)

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

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

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

public final void
setReaderBuilder(IonReaderBuilder
the reader builder to use in built systems. If unset, each system will be built with IonReaderBuilder#standard().
builder)

Sets the reader builder whose options will be used to use when building an IonSystem.

public final void
setStreamCopyOptimized(boolean optimized)

Declares whether built systems may attempt to optimize IonWriter#writeValue(IonReader) by copying raw source data.

public static IonSystemBuilder
standard()

The standard builder of IonSystems.

public final IonSystemBuilder
withCatalog(IonCatalog
the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.
catalog)

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

public final IonSystemBuilder
withIonBinaryWriterBuilder(IonBinaryWriterBuilder
the writer builder to use in built systems. If unset, each system will be built with IonBinaryWriterBuilder#standard().
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.

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

Declares the text writer builder whose options will be used when building an IonSystem, returning a new mutable builder if this is immutable.

public final IonSystemBuilder
withReaderBuilder(IonReaderBuilder
the reader builder to use in built systems. If unset, each system will be built with IonReaderBuilder#standard().
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.

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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

binaryWriterBuilderback to summary
pack-priv IonBinaryWriterBuilder binaryWriterBuilder
myCatalogback to summary
pack-priv IonCatalog myCatalog
myStreamCopyOptimizedback to summary
pack-priv boolean myStreamCopyOptimized
readerBuilderback to summary
pack-priv IonReaderBuilder readerBuilder
STANDARDback to summary
private static final IonSystemBuilder STANDARD
textWriterBuilderback to summary
pack-priv IonTextWriterBuilder textWriterBuilder

Constructor Detail

IonSystemBuilderback to summary
private IonSystemBuilder()

You no touchy.

IonSystemBuilderback to summary
private IonSystemBuilder(IonSystemBuilder that)

Method Detail

buildback to summary
public final IonSystem build()

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

copyback to summary
public final IonSystemBuilder copy()

Creates a mutable copy of this builder.

Returns:IonSystemBuilder

a new builder with the same configuration as this.

getCatalogback to summary
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()
getIonBinaryWriterBuilderback to summary
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)
getIonTextWriterBuilderback to summary
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)
getReaderBuilderback to summary
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)
immutableback to summary
public IonSystemBuilder immutable()

Returns an immutable builder configured exactly like this one.

Returns:IonSystemBuilder

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

isStreamCopyOptimizedback to summary
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)
mutableback to summary
public IonSystemBuilder mutable()

Returns a mutable builder configured exactly like this one.

Returns:IonSystemBuilder

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

mutationCheckback to summary
pack-priv void mutationCheck()
setCatalogback to summary
public final void setCatalog(IonCatalog catalog)

Sets the catalog to use when building an IonSystem.

Parameters
catalog:IonCatalog

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

Exceptions
UnsupportedOperationException:
if this is immutable.
See Also
getCatalog(), withCatalog(IonCatalog), IonSystem#getCatalog()
setIonBinaryWriterBuilderback to summary
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:IonBinaryWriterBuilder

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

Exceptions
UnsupportedOperationException:
if this is immutable.
See Also
getIonBinaryWriterBuilder(), withIonBinaryWriterBuilder(IonBinaryWriterBuilder)
setIonTextWriterBuilderback to summary
public final void setIonTextWriterBuilder(IonTextWriterBuilder builder)

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

Parameters
builder:IonTextWriterBuilder

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

Exceptions
UnsupportedOperationException:
if this is immutable.
See Also
getIonTextWriterBuilder(), withIonTextWriterBuilder(IonTextWriterBuilder)
setReaderBuilderback to summary
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:IonReaderBuilder

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

Exceptions
UnsupportedOperationException:
if this is immutable.
See Also
getReaderBuilder(), withReaderBuilder(IonReaderBuilder)
setStreamCopyOptimizedback to summary
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.

Exceptions
UnsupportedOperationException:
if this is immutable.
See Also
isStreamCopyOptimized(), withStreamCopyOptimized(boolean)
standardback to summary
public static IonSystemBuilder standard()

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

The returned instance is immutable.

withCatalogback to summary
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:IonCatalog

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()
withIonBinaryWriterBuilderback to summary
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:IonBinaryWriterBuilder

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

See Also
getIonBinaryWriterBuilder(), setIonBinaryWriterBuilder(IonBinaryWriterBuilder)
withIonTextWriterBuilderback to summary
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:IonTextWriterBuilder

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)
withReaderBuilderback to summary
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:IonReaderBuilder

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

See Also
getReaderBuilder(), setReaderBuilder(IonReaderBuilder)
withStreamCopyOptimizedback to summary
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)
com.amazon.ion.system back to summary

private final Class IonSystemBuilder.Mutable

extends IonSystemBuilder
Class Inheritance

Field Summary

Inherited from com.amazon.ion.system.IonSystemBuilder:
binaryWriterBuildermyCatalogmyStreamCopyOptimizedreaderBuildertextWriterBuilder

Constructor Summary

AccessConstructor and Description
private
Mutable(IonSystemBuilder that)

Method Summary

Modifier and TypeMethod and Description
public IonSystemBuilder
immutable()

Overrides com.amazon.ion.system.IonSystemBuilder.immutable.

Returns an immutable builder configured exactly like this one.

public IonSystemBuilder
mutable()

Overrides com.amazon.ion.system.IonSystemBuilder.mutable.

Returns a mutable builder configured exactly like this one.

pack-priv void
mutationCheck()

Overrides com.amazon.ion.system.IonSystemBuilder.mutationCheck.

Inherited from com.amazon.ion.system.IonSystemBuilder:
buildcopygetCataloggetIonBinaryWriterBuildergetIonTextWriterBuildergetReaderBuilderisStreamCopyOptimizedsetCatalogsetIonBinaryWriterBuildersetIonTextWriterBuildersetReaderBuildersetStreamCopyOptimizedstandardwithCatalogwithIonBinaryWriterBuilderwithIonTextWriterBuilderwithReaderBuilderwithStreamCopyOptimized

Constructor Detail

Mutableback to summary
private Mutable(IonSystemBuilder that)

Method Detail

immutableback to summary
public IonSystemBuilder immutable()

Overrides com.amazon.ion.system.IonSystemBuilder.immutable.

Doc from com.amazon.ion.system.IonSystemBuilder.immutable.

Returns an immutable builder configured exactly like this one.

Returns:IonSystemBuilder

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

Annotations
@Override
mutableback to summary
public IonSystemBuilder mutable()

Overrides com.amazon.ion.system.IonSystemBuilder.mutable.

Doc from com.amazon.ion.system.IonSystemBuilder.mutable.

Returns a mutable builder configured exactly like this one.

Returns:IonSystemBuilder

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

Annotations
@Override
mutationCheckback to summary
pack-priv void mutationCheck()

Overrides com.amazon.ion.system.IonSystemBuilder.mutationCheck.

Annotations
@Override