software.amazon.ion.system

Class IonBinaryWriterBuilder

java.lang.Object

software.amazon.ion.system.IonWriterBuilder

software.amazon.ion.system.IonBinaryWriterBuilder

public abstract class IonBinaryWriterBuilder
extends IonWriterBuilder

The builder for creating IonWriters emitting the Ion binary format.

WARNING: This class should not be extended by code outside of this library.

Builders may be configured once and reused to construct multiple objects.

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

Nested Class Summary

Nested classes/interfaces inherited from class software.amazon.ion.system.IonWriterBuilder

IonWriterBuilder.InitialIvmHandling, IonWriterBuilder.IvmMinimizing

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IonBinaryWriterBuilder() NOT FOR APPLICATION USE!
protected	IonBinaryWriterBuilder(IonBinaryWriterBuilder that) NOT FOR APPLICATION USE!

Method Summary

Modifier and Type	Method and Description
abstract IonBinaryWriterBuilder	copy() Creates a mutable copy of this builder.
IonCatalog	getCatalog() Gets the catalog to use when building an IonWriter.
SymbolTable[]	getImports() Gets the imports that will be used to construct the initial local symbol table.
IonWriterBuilder.InitialIvmHandling	getInitialIvmHandling() Gets the strategy for emitting Ion version markers at the start of the stream.
abstract SymbolTable	getInitialSymbolTable() Gets the symbol table to use for encoded data.
IonWriterBuilder.IvmMinimizing	getIvmMinimizing() Gets the strategy for eliminating Ion version markers mid-stream.
abstract IonBinaryWriterBuilder	immutable() Returns an immutable builder configured exactly like this one.
boolean	isStreamCopyOptimized() Indicates whether built writers may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data.
abstract IonBinaryWriterBuilder	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 IonWriter.
void	setImports(SymbolTable... imports) Sets the shared symbol tables that will be used to construct the initial local symbol table.
abstract void	setInitialSymbolTable(SymbolTable symtab) Declares the symbol table to use for encoded data.
abstract void	setIsFloatBinary32Enabled(boolean enabled) Enables or disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision.
void	setStreamCopyOptimized(boolean optimized) Declares whether built writers may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data.
static IonBinaryWriterBuilder	standard() The standard builder of binary writers, with all configuration properties having their default values.
IonBinaryWriterBuilder	withCatalog(IonCatalog catalog) Declares the catalog to use when building an IonWriter, returning a new mutable builder if this is immutable.
abstract IonBinaryWriterBuilder	withFloatBinary32Disabled() Disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats.
abstract IonBinaryWriterBuilder	withFloatBinary32Enabled() Enables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision.
IonBinaryWriterBuilder	withImports(SymbolTable... imports) Declares the imports to use when building an IonWriter, returning a new mutable builder if this is immutable.
abstract IonBinaryWriterBuilder	withInitialSymbolTable(SymbolTable symtab) Declares the symbol table to use for encoded data.
IonBinaryWriterBuilder	withStreamCopyOptimized(boolean optimized) Declares whether built writers 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 software.amazon.ion.system.IonWriterBuilder

build

Methods inherited from class java.lang.Object

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

Constructor Detail

IonBinaryWriterBuilder

protected IonBinaryWriterBuilder()

NOT FOR APPLICATION USE!

IonBinaryWriterBuilder

protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that)

NOT FOR APPLICATION USE!

Method Detail

standard

public static IonBinaryWriterBuilder standard()

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

Returns:

a new, mutable builder instance.

copy

public abstract IonBinaryWriterBuilder copy()

Creates a mutable copy of this builder.

Returns:

a new builder with the same configuration as this.

immutable

public abstract IonBinaryWriterBuilder immutable()

Returns an immutable builder configured exactly like this one.

Returns:

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

mutable

public abstract IonBinaryWriterBuilder mutable()

Returns a mutable builder configured exactly like this one.

Returns:

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

withCatalog

public final IonBinaryWriterBuilder withCatalog(IonCatalog catalog)

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

Parameters:

catalog - the catalog to use in built writers. If null, the writer will be unable to resolve manually-written imports and may throw an exception.

Returns:

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

See Also:

getCatalog(), setCatalog(IonCatalog)

withImports

public final IonBinaryWriterBuilder withImports(SymbolTable... imports)

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

If the imports sequence is not null and not empty, the output stream will be bootstrapped with a local symbol table that uses the given imports.

Parameters:

imports - a sequence of shared symbol tables. The first (and only the first) may be a system table.

Returns:

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

See Also:

getImports(), setImports(SymbolTable...)

getInitialIvmHandling

public IonWriterBuilder.InitialIvmHandling getInitialIvmHandling()

Description copied from class: IonWriterBuilder

Gets the strategy for emitting Ion version markers at the start of the stream. By default, IVMs are emitted only when explicitly written or when necessary (for example, before data that's not Ion 1.0, or at the start of Ion binary output).

Specified by:

getInitialIvmHandling in class IonWriterBuilder

Returns:

always IonWriterBuilder.InitialIvmHandling.ENSURE.

getIvmMinimizing

public IonWriterBuilder.IvmMinimizing getIvmMinimizing()

Description copied from class: IonWriterBuilder

Gets the strategy for eliminating Ion version markers mid-stream. By default, IVMs are emitted as received or when necessary.

This strategy does not affect handling of IVMs at the start of the stream; that's the job of IonWriterBuilder.InitialIvmHandling.

Specified by:

getIvmMinimizing in class IonWriterBuilder

Returns:

always null.

getInitialSymbolTable

public abstract SymbolTable getInitialSymbolTable()

Gets the symbol table to use for encoded data. To avoid conflicts between different data streams, if the given instance is mutable, it will be copied when build() is called.

Returns:

a local or system symbol table. May be null, in which case the initial symbol table is that of $ion_1_0.

See Also:

setInitialSymbolTable(SymbolTable), withInitialSymbolTable(SymbolTable)

setInitialSymbolTable

public abstract void setInitialSymbolTable(SymbolTable symtab)

Declares the symbol table to use for encoded data. To avoid conflicts between different data streams, if the given instance is mutable, it will be copied when build() is called.

Parameters:

symtab - must be a local or system symbol table. May be null, in which case the initial symbol table is that of $ion_1_0.

Throws:

SubstituteSymbolTableException - if any imported table is a substitute (see SymbolTable).

See Also:

getInitialSymbolTable(), withInitialSymbolTable(SymbolTable)

withInitialSymbolTable

public abstract IonBinaryWriterBuilder withInitialSymbolTable(SymbolTable symtab)

Declares the symbol table to use for encoded data. To avoid conflicts between different data streams, if the given instance is mutable, it will be copied when build() is called.

Parameters:

symtab - must be a local or system symbol table. May be null, in which case the initial symbol table is that of $ion_1_0.

Throws:

SubstituteSymbolTableException - if any imported table is a substitute (see SymbolTable).

setIsFloatBinary32Enabled

public abstract void setIsFloatBinary32Enabled(boolean enabled)

Enables or disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision. By default Binary32 support is disabled to ensure the broadest compatibility with existing Ion implementations. Historically, implementations were only able to read Binary64 values.

When enabled, floats are evaluated for a possible loss of data at single precision. If the value can be represented in single precision without data loss, it is written as a 4-byte, Binary32 value. Floats which cannot be represented as single-precision values are written as 8-byte, Binary64 values (this is the legacy behavior for all floats, regardless of value).

Parameters:

enabled - true to enable writing 4-byte floats, false to always write 8-byte floats.

See Also:

withFloatBinary32Enabled(), withFloatBinary32Disabled()

withFloatBinary32Enabled

public abstract IonBinaryWriterBuilder withFloatBinary32Enabled()

Enables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision. By default Binary32 support is disabled to ensure the broadest compatibility with existing Ion implementations. Historically, implementations were only able to read Binary64 values.

When enabled, floats are evaluated for a possible loss of data at single precision. If the value can be represented in single precision without data loss, it is written as a 4-byte, Binary32 value. Floats which cannot be represented as single-precision values are written as 8-byte, Binary64 values (this is the legacy behavior for all floats, regardless of value).

See Also:

setIsFloatBinary32Enabled(boolean), withFloatBinary32Disabled()

withFloatBinary32Disabled

public abstract IonBinaryWriterBuilder withFloatBinary32Disabled()

Disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats. This is the default behavior.

When disabled, floats are always written as 8-byte, Binary64 values regardless of value. This is the legacy behavior for all Ion binary writers and ensures the boarded compatibility with other Ion consumers.

Parameters:

enabled - true to enable writing 4-byte floats, false to always write 8-byte floats.

See Also:

setIsFloatBinary32Enabled(boolean), withFloatBinary32Enabled()

isStreamCopyOptimized

public boolean isStreamCopyOptimized()

Indicates whether built writers 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 void setStreamCopyOptimized(boolean optimized)

Declares whether built writers 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:

UnsupportedOperationException - if this is immutable.

See Also:

isStreamCopyOptimized(), withStreamCopyOptimized(boolean)

withStreamCopyOptimized

public final IonBinaryWriterBuilder withStreamCopyOptimized(boolean optimized)

Declares whether built writers 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)

mutationCheck

protected void mutationCheck()

NOT FOR APPLICATION USE!

getCatalog

public final IonCatalog getCatalog()

Gets the catalog to use when building an IonWriter. The catalog is needed to resolve manually-written imports (not common). By default, this property is null.

See Also:

setCatalog(IonCatalog), withCatalog(IonCatalog)

setCatalog

public void setCatalog(IonCatalog catalog)

Sets the catalog to use when building an IonWriter.

Parameters:

catalog - the catalog to use in built writers. If null, the writer will be unable to resolve manually-written imports and may throw an exception.

Throws:

UnsupportedOperationException - if this is immutable.

See Also:

getCatalog(), withCatalog(IonCatalog)

getImports

public final SymbolTable[] getImports()

Gets the imports that will be used to construct the initial local symbol table.

Returns:

may be null or empty.

See Also:

setImports(SymbolTable...), withImports(SymbolTable...)

setImports

public void setImports(SymbolTable... imports)

Sets the shared symbol tables that will be used to construct the initial local symbol table.

If the imports sequence is not null and not empty, the output stream will be bootstrapped with a local symbol table that uses the given imports.

Parameters:

imports - a sequence of shared symbol tables. The first (and only the first) may be a system table.

Throws:

UnsupportedOperationException - if this is immutable.

See Also:

getImports(), withImports(SymbolTable...)