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.
| Modifier and Type | Field and Description |
|---|---|
| private boolean |
| Access | Constructor and Description |
|---|---|
| protected | |
| protected |
| Modifier and Type | Method and Description |
|---|---|
| public abstract IonBinaryWriterBuilder | copy()
Implements abstract com. Creates a mutable copy of this builder. |
| public IonWriterBuilder. | Returns: alwaysIonWriterBuilder..Implements abstract com. 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.Gets the symbol table to use for encoded data. |
| public IonWriterBuilder. | Returns: always null.Implements abstract com. Gets the strategy for eliminating Ion version markers mid-stream. |
| public abstract IonBinaryWriterBuilder | immutable()
Implements abstract com. Returns an immutable builder configured exactly like this one. |
| public boolean | isStreamCopyOptimized()
Indicates whether built writers may attempt to optimize
|
| public abstract IonBinaryWriterBuilder | mutable()
Implements abstract com. 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
symtab)$ion_1_0.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.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
|
| public static IonBinaryWriterBuilder | Returns: a new, mutable builder instance.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. Declares the catalog to use when building an |
| 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. Declares the imports to use when building an |
| 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
symtab)$ion_1_0.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
|
| myStreamCopyOptimized | back to summary |
|---|---|
| private boolean myStreamCopyOptimized | |
| IonBinaryWriterBuilder | back to summary |
|---|---|
| protected IonBinaryWriterBuilder() NOT FOR APPLICATION USE! | |
| IonBinaryWriterBuilder | back to summary |
|---|---|
| protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that) NOT FOR APPLICATION USE! | |
| copy | back to summary |
|---|---|
| public abstract IonBinaryWriterBuilder copy() Implements abstract com. Doc from com. Creates a mutable copy of this builder.
| |
| getInitialIvmHandling | back to summary |
|---|---|
| public IonWriterBuilder. Implements abstract com. Doc from com. 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).
| |
| getInitialSymbolTable | back 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
| |
| getIvmMinimizing | back to summary |
|---|---|
| public IonWriterBuilder. Implements abstract com. Doc from com. 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
| |
| immutable | back to summary |
|---|---|
| public abstract IonBinaryWriterBuilder immutable() Implements abstract com. Doc from com. Returns an immutable builder configured exactly like this one.
| |
| isStreamCopyOptimized | back to summary |
|---|---|
| public boolean isStreamCopyOptimized() Indicates whether built writers may attempt to optimize
| |
| mutable | back to summary |
|---|---|
| public abstract IonBinaryWriterBuilder mutable() Implements abstract com. Doc from com. Returns a mutable builder configured exactly like this one.
| |
| setInitialSymbolTable | back 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
| |
| setIsFloatBinary32Enabled | back 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).
| |
| setLocalSymbolTableAppendEnabled | back 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. | |
| setStreamCopyOptimized | back to summary |
|---|---|
| public void setStreamCopyOptimized(boolean optimized) Declares whether built writers may attempt to optimize
This feature is experimental! Please test thoroughly and report any issues.
| |
| standard | back to summary |
|---|---|
| public static IonBinaryWriterBuilder standard() The standard builder of binary writers, with all configuration properties having their default values.
| |
| withAutoFlushEnabled | back 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.
| |
| withBlockSize | back to summary |
|---|---|
| public abstract IonBinaryWriterBuilder withBlockSize(int size) Specify the block size for write buffer.
| |
| withCatalog | back to summary |
|---|---|
| public final IonBinaryWriterBuilder withCatalog(IonCatalog catalog) Overrides com. Doc from com. Declares the catalog to use when building an
| |
| withFloatBinary32Disabled | back 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. | |
| withFloatBinary32Enabled | back 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). | |
| withImports | back to summary |
|---|---|
| public final IonBinaryWriterBuilder withImports(SymbolTable... imports) Overrides com. Doc from com. Declares the imports to use when building an
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
| |
| withInitialSymbolTable | back 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
| |
| withLocalSymbolTableAppendDisabled | back 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. | |
| withLocalSymbolTableAppendEnabled | back 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. | |
| withStreamCopyOptimized | back to summary |
|---|---|
| public final IonBinaryWriterBuilder withStreamCopyOptimized(boolean optimized) Declares whether built writers may attempt to optimize
This feature is experimental! Please test thoroughly and report any issues. | |