public abstract class IonBinaryWriterBuilder extends IonWriterBuilder
IonWriter
s 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.
IonWriterBuilder.InitialIvmHandling, IonWriterBuilder.IvmMinimizing
Modifier | Constructor and Description |
---|---|
protected |
IonBinaryWriterBuilder()
NOT FOR APPLICATION USE!
|
protected |
IonBinaryWriterBuilder(IonBinaryWriterBuilder that)
NOT FOR APPLICATION USE!
|
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. |
build
protected IonBinaryWriterBuilder()
protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that)
public static IonBinaryWriterBuilder standard()
public abstract IonBinaryWriterBuilder copy()
this
.public abstract IonBinaryWriterBuilder immutable()
public abstract IonBinaryWriterBuilder mutable()
public final IonBinaryWriterBuilder withCatalog(IonCatalog catalog)
IonWriter
,
returning a new mutable builder if this is immutable.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.getCatalog()
,
setCatalog(IonCatalog)
public final IonBinaryWriterBuilder withImports(SymbolTable... imports)
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
.
imports
- a sequence of shared symbol tables.
The first (and only the first) may be a system table.getImports()
,
setImports(SymbolTable...)
public IonWriterBuilder.InitialIvmHandling getInitialIvmHandling()
IonWriterBuilder
getInitialIvmHandling
in class IonWriterBuilder
IonWriterBuilder.InitialIvmHandling.ENSURE
.public IonWriterBuilder.IvmMinimizing getIvmMinimizing()
IonWriterBuilder
This strategy does not affect handling of IVMs at the start of the
stream; that's the job of IonWriterBuilder.InitialIvmHandling
.
getIvmMinimizing
in class IonWriterBuilder
public abstract SymbolTable getInitialSymbolTable()
build()
is called.$ion_1_0
.setInitialSymbolTable(SymbolTable)
,
withInitialSymbolTable(SymbolTable)
public abstract void setInitialSymbolTable(SymbolTable symtab)
build()
is called.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
.SubstituteSymbolTableException
- if any imported table is a substitute (see SymbolTable
).getInitialSymbolTable()
,
withInitialSymbolTable(SymbolTable)
public abstract IonBinaryWriterBuilder withInitialSymbolTable(SymbolTable symtab)
build()
is called.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
.SubstituteSymbolTableException
- if any imported table is a substitute (see SymbolTable
).public abstract void setIsFloatBinary32Enabled(boolean enabled)
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).
enabled
- true
to enable writing 4-byte floats,
false
to always write 8-byte floats.withFloatBinary32Enabled()
,
withFloatBinary32Disabled()
public abstract IonBinaryWriterBuilder withFloatBinary32Enabled()
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).
public abstract IonBinaryWriterBuilder withFloatBinary32Disabled()
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.
enabled
- true
to enable writing 4-byte floats,
false
to always write 8-byte floats.setIsFloatBinary32Enabled(boolean)
,
withFloatBinary32Enabled()
public boolean isStreamCopyOptimized()
IonWriter.writeValue(IonReader)
by copying raw source data.
By default, this property is false.public void setStreamCopyOptimized(boolean optimized)
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.
UnsupportedOperationException
- if this is immutable.isStreamCopyOptimized()
,
withStreamCopyOptimized(boolean)
public final IonBinaryWriterBuilder withStreamCopyOptimized(boolean optimized)
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.
protected void mutationCheck()
public final IonCatalog getCatalog()
IonWriter
.
The catalog is needed to resolve manually-written imports (not common).
By default, this property is null.setCatalog(IonCatalog)
,
withCatalog(IonCatalog)
public void setCatalog(IonCatalog catalog)
IonWriter
.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.UnsupportedOperationException
- if this is immutable.getCatalog()
,
withCatalog(IonCatalog)
public final SymbolTable[] getImports()
setImports(SymbolTable...)
,
withImports(SymbolTable...)
public void setImports(SymbolTable... imports)
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
.
imports
- a sequence of shared symbol tables.
The first (and only the first) may be a system table.UnsupportedOperationException
- if this is immutable.getImports()
,
withImports(SymbolTable...)