Package com.amazon.ion.impl

Class _Private_IonBinaryWriterBuilder

java.lang.Object

com.amazon.ion.system.IonWriterBuilder

com.amazon.ion.system.IonBinaryWriterBuilder

com.amazon.ion.impl._Private_IonBinaryWriterBuilder

public class _Private_IonBinaryWriterBuilder
extends IonBinaryWriterBuilder

NOT FOR APPLICATION USE!

Nested Class Summary

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

IonWriterBuilder.InitialIvmHandling, IonWriterBuilder.IvmMinimizing

Method Summary

Modifier and Type	Method	Description
final IonWriter	build(OutputStream out)	Builds a new writer based on this builder's configuration properties.
final IonBinaryWriter	buildLegacy()	Deprecated.
final _Private_IonBinaryWriterBuilder	copy()
final IonCatalog	getCatalog()	Gets the catalog to use when building an IonWriter.
final SymbolTable[]	getImports()	Gets the imports that will be used to construct the initial local symbol table.
SymbolTable	getInitialSymbolTable()	Gets the symbol table to use for encoded data.
ValueFactory	getSymtabValueFactory()
_Private_IonBinaryWriterBuilder	immutable()
_Private_IonBinaryWriterBuilder	mutable()
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.
void	setInitialSymbolTable(SymbolTable symtab)	Declares the symbol table to use for encoded data.
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	setLocalSymbolTableAppendEnabled(boolean enabled)	Enables or disables writing local symbol tables that append symbols to the current symbol table.
void	setStreamCopyOptimized(boolean optimized)	Declares whether built writers may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data.
void	setSymtabValueFactory(ValueFactory factory)
static _Private_IonBinaryWriterBuilder	standard()
_Private_IonBinaryWriterBuilder	withFloatBinary32Disabled()	Disables writing Binary32 (4-byte, single precision, IEEE-754) values for floats.
_Private_IonBinaryWriterBuilder	withFloatBinary32Enabled()	Enables writing Binary32 (4-byte, single precision, IEEE-754) values for floats when there would be no loss in precision.
_Private_IonBinaryWriterBuilder	withInitialSymbolTable(SymbolTable symtab)	Defaults to $ion_1_0 if null.
_Private_IonBinaryWriterBuilder	withLocalSymbolTableAppendDisabled()	Disables writing local symbol tables that append symbols to the current symbol table.
_Private_IonBinaryWriterBuilder	withLocalSymbolTableAppendEnabled()	Enables writing local symbol tables that append symbols to the current symbol table.
_Private_IonBinaryWriterBuilder	withSymtabValueFactory(ValueFactory factory)

Methods inherited from class com.amazon.ion.system.IonBinaryWriterBuilder

getInitialIvmHandling, getIvmMinimizing, isStreamCopyOptimized, withCatalog, withImports, withStreamCopyOptimized

Methods inherited from class java.lang.Object

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

Method Details

standard

public static _Private_IonBinaryWriterBuilder standard()

Returns:

a new mutable builder.

copy

public final _Private_IonBinaryWriterBuilder copy()

Specified by:

copy in class IonBinaryWriterBuilder

immutable

public _Private_IonBinaryWriterBuilder immutable()

Specified by:

immutable in class IonBinaryWriterBuilder

mutable

public _Private_IonBinaryWriterBuilder mutable()

Specified by:

mutable in class IonBinaryWriterBuilder

getSymtabValueFactory

public ValueFactory getSymtabValueFactory()

setSymtabValueFactory

public void setSymtabValueFactory(ValueFactory factory)

withSymtabValueFactory

public _Private_IonBinaryWriterBuilder withSymtabValueFactory(ValueFactory factory)

getInitialSymbolTable

public SymbolTable getInitialSymbolTable()

Description copied from class: IonBinaryWriterBuilder

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.

Specified by:

getInitialSymbolTable in class IonBinaryWriterBuilder

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:

• IonBinaryWriterBuilder.setInitialSymbolTable(SymbolTable)
• IonBinaryWriterBuilder.withInitialSymbolTable(SymbolTable)

setInitialSymbolTable

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

Specified by:

setInitialSymbolTable in class IonBinaryWriterBuilder

Parameters:

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

Throws:

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

See Also:

• IonBinaryWriterBuilder.getInitialSymbolTable()
• IonBinaryWriterBuilder.withInitialSymbolTable(SymbolTable)

withInitialSymbolTable

public _Private_IonBinaryWriterBuilder withInitialSymbolTable(SymbolTable symtab)

Defaults to $ion_1_0 if null.

Specified by:

withInitialSymbolTable in class IonBinaryWriterBuilder

Parameters:

symtab - may be null.

setLocalSymbolTableAppendEnabled

public void setLocalSymbolTableAppendEnabled(boolean enabled)

Description copied from class: IonBinaryWriterBuilder

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

Specified by:

setLocalSymbolTableAppendEnabled in class IonBinaryWriterBuilder

withLocalSymbolTableAppendEnabled

public _Private_IonBinaryWriterBuilder withLocalSymbolTableAppendEnabled()

Description copied from class: IonBinaryWriterBuilder

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

Specified by:

withLocalSymbolTableAppendEnabled in class IonBinaryWriterBuilder

withLocalSymbolTableAppendDisabled

public _Private_IonBinaryWriterBuilder withLocalSymbolTableAppendDisabled()

Description copied from class: IonBinaryWriterBuilder

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

Specified by:

withLocalSymbolTableAppendDisabled in class IonBinaryWriterBuilder

setIsFloatBinary32Enabled

public void setIsFloatBinary32Enabled(boolean enabled)

Description copied from class: IonBinaryWriterBuilder

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

Specified by:

setIsFloatBinary32Enabled in class IonBinaryWriterBuilder

Parameters:

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

See Also:

• IonBinaryWriterBuilder.withFloatBinary32Enabled()
• IonBinaryWriterBuilder.withFloatBinary32Disabled()

withFloatBinary32Enabled

public _Private_IonBinaryWriterBuilder withFloatBinary32Enabled()

Description copied from class: IonBinaryWriterBuilder

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

Specified by:

withFloatBinary32Enabled in class IonBinaryWriterBuilder

See Also:

• IonBinaryWriterBuilder.setIsFloatBinary32Enabled(boolean)
• IonBinaryWriterBuilder.withFloatBinary32Disabled()

withFloatBinary32Disabled

public _Private_IonBinaryWriterBuilder withFloatBinary32Disabled()

Description copied from class: IonBinaryWriterBuilder

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.

Specified by:

withFloatBinary32Disabled in class IonBinaryWriterBuilder

See Also:

• IonBinaryWriterBuilder.setIsFloatBinary32Enabled(boolean)
• IonBinaryWriterBuilder.withFloatBinary32Enabled()

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.

See Also:

• getImports()
• withImports(SymbolTable...)

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.

See Also:

• getCatalog()
• withCatalog(IonCatalog)

setStreamCopyOptimized

public void setStreamCopyOptimized(boolean optimized)

Description copied from class: IonBinaryWriterBuilder

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.

Overrides:

setStreamCopyOptimized in class IonBinaryWriterBuilder

See Also:

• IonBinaryWriterBuilder.isStreamCopyOptimized()
• IonBinaryWriterBuilder.withStreamCopyOptimized(boolean)

build

public final IonWriter build(OutputStream out)

Description copied from class: IonWriterBuilder

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

Specified by:

build in class IonWriterBuilder

Parameters:

out - the stream that will receive Ion data. Must not be null.

Returns:

a new IonWriter instance; not null.

buildLegacy

@Deprecated
public final IonBinaryWriter buildLegacy()

Deprecated.

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)

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