Package com.amazon.ion.system

Class IonBinaryWriterBuilder

java.lang.Object
com.amazon.ion.system.IonWriterBuilder
com.amazon.ion.system.IonBinaryWriterBuilder
Direct Known Subclasses:
_Private_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.

  • Constructor Details

    • IonBinaryWriterBuilder

      protected IonBinaryWriterBuilder()
      NOT FOR APPLICATION USE!

    • IonBinaryWriterBuilder

      protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that)
      NOT FOR APPLICATION USE!

  • Method Details

    • 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()

    • immutable

      public abstract IonBinaryWriterBuilder immutable()

    • mutable

      public abstract IonBinaryWriterBuilder mutable()

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

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

    • 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

      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:

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

    • setLocalSymbolTableAppendEnabled

      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.

    • withLocalSymbolTableAppendEnabled

      public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendEnabled()
      Enables writing local symbol tables that append symbols to the current symbol table. This functionality is disabled by default.

    • withLocalSymbolTableAppendDisabled

      public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendDisabled()
      Disables writing local symbol tables that append symbols to the current symbol table. This functionality is disabled by default.

    • 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

      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:

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

      See Also:

    • 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

      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:

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

    • 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

      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:

    • 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

      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: