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

public abstract Class IonBinaryWriterBuilder

extends IonWriterBuilderBase<IonBinaryWriterBuilder>
Class Inheritance
Known Direct Subclasses
com.amazon.ion.impl._Private_IonBinaryWriterBuilder
Imports
com.amazon.ion.IonCatalog, .IonReader, .IonWriter, .SubstituteSymbolTableException, .SymbolTable, com.amazon.ion.impl._Private_IonBinaryWriterBuilder

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.

Field Summary

Modifier and TypeField and Description
private boolean

Constructor Summary

AccessConstructor and Description
protected
IonBinaryWriterBuilder()

NOT FOR APPLICATION USE!

protected
IonBinaryWriterBuilder(IonBinaryWriterBuilder that)

NOT FOR APPLICATION USE!

Method Summary

Modifier and TypeMethod and Description
public abstract IonBinaryWriterBuilder
copy()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.copy.

Creates a mutable copy of this builder.

public IonWriterBuilder.InitialIvmHandling
getInitialIvmHandling()

Implements abstract com.amazon.ion.system.IonWriterBuilder.getInitialIvmHandling.

Gets the strategy for emitting Ion version markers at the start of the stream.

public abstract SymbolTable

Returns:

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

Gets the symbol table to use for encoded data.

public IonWriterBuilder.IvmMinimizing

Returns:

always null.
getIvmMinimizing
()

Implements abstract com.amazon.ion.system.IonWriterBuilder.getIvmMinimizing.

Gets the strategy for eliminating Ion version markers mid-stream.

public abstract IonBinaryWriterBuilder
immutable()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.immutable.

Returns an immutable builder configured exactly like this one.

public boolean
isStreamCopyOptimized()

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

public abstract IonBinaryWriterBuilder
mutable()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.mutable.

Returns a mutable builder configured exactly like this one.

public abstract void
setInitialSymbolTable(SymbolTable
must be a local or system symbol table. May be null, in which case the initial symbol table is that of $ion_1_0.
symtab
)

Declares the symbol table to use for encoded data.

public abstract void
setIsFloatBinary32Enabled(boolean
true to enable writing 4-byte floats, false to always write 8-byte floats.
enabled
)

Enables or disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision.

public abstract void
setLocalSymbolTableAppendEnabled(boolean enabled)

Enables or disables writing local symbol tables that append symbols to the current symbol table.

public void
setStreamCopyOptimized(boolean optimized)

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

public static IonBinaryWriterBuilder

Returns:

a new, mutable builder instance.
standard
()

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

public abstract IonBinaryWriterBuilder
withAutoFlushEnabled(boolean
A boolean parameter indicating whether this functionality is enabled or not.
autoFlushEnabled
)

Auto-flush enables automatic execution of flush operations during the write process.

public abstract IonBinaryWriterBuilder
withBlockSize(int
represent the specified block size in bytes. If this functionality is not set, the default block size is 32768 bytes.
size
)

Specify the block size for write buffer.

public final IonBinaryWriterBuilder
withCatalog(IonCatalog
the catalog to use in built writers. If null, the writer will be unable to resolve manually-written imports and may throw an exception.
catalog
)

Overrides com.amazon.ion.system.IonWriterBuilderBase.withCatalog.

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

public abstract IonBinaryWriterBuilder
withFloatBinary32Disabled()

Disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats.

public abstract IonBinaryWriterBuilder
withFloatBinary32Enabled()

Enables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision.

public final IonBinaryWriterBuilder
withImports(SymbolTable...
a sequence of shared symbol tables. The first (and only the first) may be a system table.
imports
)

Overrides com.amazon.ion.system.IonWriterBuilderBase.withImports.

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

public abstract IonBinaryWriterBuilder
withInitialSymbolTable(SymbolTable
must be a local or system symbol table. May be null, in which case the initial symbol table is that of $ion_1_0.
symtab
)

Declares the symbol table to use for encoded data.

public abstract IonBinaryWriterBuilder
withLocalSymbolTableAppendDisabled()

Disables writing local symbol tables that append symbols to the current symbol table.

public abstract IonBinaryWriterBuilder
withLocalSymbolTableAppendEnabled()

Enables writing local symbol tables that append symbols to the current symbol table.

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.

Inherited from com.amazon.ion.system.IonWriterBuilderBase:
getCataloggetImportsmutationChecksetCatalogsetImports

Field Detail

myStreamCopyOptimizedback to summary
private boolean myStreamCopyOptimized

Constructor Detail

IonBinaryWriterBuilderback to summary
protected IonBinaryWriterBuilder()

NOT FOR APPLICATION USE!

IonBinaryWriterBuilderback to summary
protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that)

NOT FOR APPLICATION USE!

Method Detail

copyback to summary
public abstract IonBinaryWriterBuilder copy()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.copy.

Doc from com.amazon.ion.system.IonWriterBuilderBase.copy.

Creates a mutable copy of this builder.

Returns:IonBinaryWriterBuilder

a new builder with the same configuration as this.

Annotations
@Override
getInitialIvmHandlingback to summary
public IonWriterBuilder.InitialIvmHandling getInitialIvmHandling()

Implements abstract com.amazon.ion.system.IonWriterBuilder.getInitialIvmHandling.

Doc from com.amazon.ion.system.IonWriterBuilder.getInitialIvmHandling.

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

Returns:IonWriterBuilder.InitialIvmHandling

always IonWriterBuilder.InitialIvmHandling#ENSURE.

Annotations
@Override
getInitialSymbolTableback to summary
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:SymbolTable

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)
getIvmMinimizingback to summary
public IonWriterBuilder.IvmMinimizing getIvmMinimizing()

Implements abstract com.amazon.ion.system.IonWriterBuilder.getIvmMinimizing.

Doc from com.amazon.ion.system.IonWriterBuilder.getIvmMinimizing.

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

Returns:IonWriterBuilder.IvmMinimizing

always null.

Annotations
@Override
immutableback to summary
public abstract IonBinaryWriterBuilder immutable()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.immutable.

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

Returns an immutable builder configured exactly like this one.

Returns:IonBinaryWriterBuilder

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

Annotations
@Override
isStreamCopyOptimizedback to summary
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)
mutableback to summary
public abstract IonBinaryWriterBuilder mutable()

Implements abstract com.amazon.ion.system.IonWriterBuilderBase.mutable.

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

Returns a mutable builder configured exactly like this one.

Returns:IonBinaryWriterBuilder

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

Annotations
@Override
setInitialSymbolTableback to summary
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:SymbolTable

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

Exceptions
SubstituteSymbolTableException:
if any imported table is a substitute (see SymbolTable).
See Also
getInitialSymbolTable(), withInitialSymbolTable(SymbolTable)
setIsFloatBinary32Enabledback to summary
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:boolean

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

See Also
IonBinaryWriterBuilder#withFloatBinary32Enabled, IonBinaryWriterBuilder#withFloatBinary32Disabled
setLocalSymbolTableAppendEnabledback to summary
public abstract void setLocalSymbolTableAppendEnabled(boolean enabled)

Enables or disables writing local symbol tables that append symbols to the current symbol table. This functionality is disabled by default.

setStreamCopyOptimizedback to summary
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.

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

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

Returns:IonBinaryWriterBuilder

a new, mutable builder instance.

withAutoFlushEnabledback to summary
public abstract IonBinaryWriterBuilder withAutoFlushEnabled(boolean autoFlushEnabled)

Auto-flush enables automatic execution of flush operations during the write process. When auto-flush is enabled and a new block allocation becomes necessary while writing the top-level value, a new block will be allocated. The data writing process will then continue uninterrupted until the top-level value is complete. After completing the top-level value that crosses the block boundary, the flush operation will be executed. This feature optimizes performance of the writing of long data streams by reducing block allocations. Additionally, setting a larger block size can further tune performance when auto-flush is enabled. A larger block size leads to fewer block allocations and reduces the frequency of flush operations when auto-flush is enabled. Here is where you can set up the block size of write buffer. Auto-flush is disabled by default and the default block size is 32K.

Parameters
autoFlushEnabled:boolean

A boolean parameter indicating whether this functionality is enabled or not.

withBlockSizeback to summary
public abstract IonBinaryWriterBuilder withBlockSize(int size)

Specify the block size for write buffer.

Parameters
size:int

represent the specified block size in bytes. If this functionality is not set, the default block size is 32768 bytes.

withCatalogback to summary
public final IonBinaryWriterBuilder withCatalog(IonCatalog catalog)

Overrides com.amazon.ion.system.IonWriterBuilderBase.withCatalog.

Doc from com.amazon.ion.system.IonWriterBuilderBase.withCatalog.

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

Parameters
catalog:IonCatalog

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

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

Annotations
@Override
withFloatBinary32Disabledback to summary
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.

See Also
IonBinaryWriterBuilder#setIsFloatBinary32Enabled(boolean), IonBinaryWriterBuilder#withFloatBinary32Enabled
withFloatBinary32Enabledback to summary
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
IonBinaryWriterBuilder#setIsFloatBinary32Enabled(boolean), IonBinaryWriterBuilder#withFloatBinary32Disabled
withImportsback to summary
public final IonBinaryWriterBuilder withImports(SymbolTable... imports)

Overrides com.amazon.ion.system.IonWriterBuilderBase.withImports.

Doc from com.amazon.ion.system.IonWriterBuilderBase.withImports.

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:SymbolTable[]

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

Returns:IonBinaryWriterBuilder

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

Annotations
@Override
withInitialSymbolTableback to summary
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:SymbolTable

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

Exceptions
SubstituteSymbolTableException:
if any imported table is a substitute (see SymbolTable).
withLocalSymbolTableAppendDisabledback to summary
public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendDisabled()

Disables writing local symbol tables that append symbols to the current symbol table. This functionality is disabled by default.

withLocalSymbolTableAppendEnabledback to summary
public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendEnabled()

Enables writing local symbol tables that append symbols to the current symbol table. This functionality is disabled by default.

withStreamCopyOptimizedback to summary
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)