Package com.amazon.ion.system

Class 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 Detail

      • IonBinaryWriterBuilder

        protected IonBinaryWriterBuilder()
        NOT FOR APPLICATION USE!

      • IonBinaryWriterBuilder

        protected IonBinaryWriterBuilder​(IonBinaryWriterBuilder that)
        NOT FOR APPLICATION USE!

    • Method Detail

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

      • 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:
        getCatalog(), setCatalog(IonCatalog)

      • 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:
        getImports(), setImports(SymbolTable...)

      • 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(SymbolTable), withInitialSymbolTable(SymbolTable)

      • 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:
        getInitialSymbolTable(), withInitialSymbolTable(SymbolTable)

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

      • 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:
        setIsFloatBinary32Enabled(boolean), withFloatBinary32Disabled()

      • 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:
        setIsFloatBinary32Enabled(boolean), withFloatBinary32Enabled()

      • 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:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        isStreamCopyOptimized(), withStreamCopyOptimized(boolean)

      • mutationCheck

        protected void mutationCheck()
        NOT FOR APPLICATION USE!

      • 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:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getCatalog(), withCatalog(IonCatalog)

      • 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:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getImports(), withImports(SymbolTable...)