Package com.amazon.ion.system

Class IonTextWriterBuilder

  • Direct Known Subclasses:
    _Private_IonTextWriterBuilder
    public abstract class IonTextWriterBuilder
extends IonWriterBuilder
    The builder for creating IonWriters emitting the Ion text syntax.

    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.

    The most general and correct approach is to use the standard() builder: 

        IonWriter w = IonTextWriterBuilder.standard().build(outputStream);
    The standard configuration gives a direct representation of what's written, including version markers and local symbol tables. That's good for diagnostics but it may be more than you want in many situations. In such cases the minimal() or pretty() builders (or a combination) may give more satisfying output: 
        IonWriter w = IonTextWriterBuilder.minimal()
                                      .withPrettyPrinting()
                                      .build(outputStream);

    Configuration properties follow the standard JavaBeans idiom in order to be friendly to dependency injection systems. They also provide alternative with...() mutation methods that enable a more fluid style.

    Auto-flushing

    IonWriters created by this builder auto-flush to the underlying data sink after writing each top-level value in the context of the writer.

    Currently, there is no configuration point available to disable the auto-flushing mechanism. Please vote on issue amazon-ion/ion-java/issues/32 if you require it.

    • Field Detail

      • ASCII

        public static final java.nio.charset.Charset ASCII
        The "US-ASCII" charset.

      • UTF8

        public static final java.nio.charset.Charset UTF8
        The "UTF-8" charset.

    • Constructor Detail

      • IonTextWriterBuilder

        protected IonTextWriterBuilder()
        NOT FOR APPLICATION USE!

      • IonTextWriterBuilder

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

    • Method Detail

      • standard

        public static IonTextWriterBuilder standard()
        The standard builder of text IonWriters, with all configuration properties having their default values. The resulting output is a direct representation of what's written to the writer, including version markers and local symbol tables.
        Returns:
        a new, mutable builder instance.
        See Also:
        minimal(), pretty(), json()

      • minimal

        public static IonTextWriterBuilder minimal()
        Creates a builder configured to minimize system data, eliminating local symbol tables and minimizing version markers.
        Returns:
        a new, mutable builder instance.
        See Also:
        withMinimalSystemData()

      • pretty

        public static IonTextWriterBuilder pretty()
        Creates a builder preconfigured for basic pretty-printing.

        The specifics of this configuration may change between releases of this library, so automated processes should not depend on the exact output formatting. In particular, there's currently no promise regarding handling of system data.

        Returns:
        a new, mutable builder instance.
        See Also:
        withPrettyPrinting()

      • withCatalog

        public final IonTextWriterBuilder 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 IonTextWriterBuilder 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...)

      • getCharset

        public final java.nio.charset.Charset getCharset()
        Gets the charset denoting the output encoding. Only ASCII and UTF-8 are supported.
        Returns:
        may be null, denoting the default of UTF-8.
        See Also:
        setCharset(Charset), withCharset(Charset)

      • setCharset

        public void setCharset​(java.nio.charset.Charset charset)
        Sets the charset denoting the output encoding. Only ASCII and UTF-8 are supported; applications can use the helper constants ASCII and UTF8.
        Parameters:
        charset - may be null, denoting the default of UTF-8.
        Throws:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getCharset(), withCharset(Charset)

      • withCharset

        public final IonTextWriterBuilder withCharset​(java.nio.charset.Charset charset)
        Declares the charset denoting the output encoding, returning a new mutable builder if this is immutable. Only ASCII and UTF-8 are supported; applications can use the helper constants ASCII and UTF8.
        Parameters:
        charset - may be null, denoting the default of UTF-8.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.
        See Also:
        getCharset(), setCharset(Charset)

      • withCharsetAscii

        public final IonTextWriterBuilder withCharsetAscii()
        Declares the output encoding to be US-ASCII.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.

      • withPrettyPrinting

        public abstract IonTextWriterBuilder withPrettyPrinting()
        Declares that this builder should use basic pretty-printing. Does not alter the handling of system data. Calling this method alters several other configuration properties, so code should call it first, then make any necessary overrides.

        The specifics of this configuration may change between releases of this library, so automated processes should not depend on the exact output formatting.

        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.

      • withJsonDowngrade

        public abstract IonTextWriterBuilder withJsonDowngrade()
        Declares that this builder should downgrade the writers' output to JSON compatibility. This format cannot round-trip back to Ion with full fidelity.

        The specific conversions are as follows:

        • System data is suppressed per withMinimalSystemData().
        • All annotations are suppressed.
        • Nulls of any type are printed as JSON null.
        • Blobs are printed as strings, containing Base64.
        • Clobs are printed as strings, containing only Unicode code points U+00 through U+FF.
        • Sexps are printed as lists.
        • Symbols are printed as strings.
        • Timestamps are printed as strings, using Ion timestamp format.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.

      • setInitialIvmHandling

        public void setInitialIvmHandling​(IonWriterBuilder.InitialIvmHandling handling)
        Sets 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).
        Parameters:
        handling - the initial IVM strategy. Null indicates that explicitly-written IVMs will be emitted.
        Throws:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getInitialIvmHandling(), withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)

      • setIvmMinimizing

        public void setIvmMinimizing​(IonWriterBuilder.IvmMinimizing minimizing)
        Sets the strategy for reducing or eliminating non-initial Ion version markers. When null, IVMs are emitted as they are written.
        Parameters:
        minimizing - the IVM minimization strategy. Null indicates that all explicitly-written IVMs will be emitted.
        Throws:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getIvmMinimizing(), withIvmMinimizing(IonWriterBuilder.IvmMinimizing)

      • withIvmMinimizing

        public final IonTextWriterBuilder withIvmMinimizing​(IonWriterBuilder.IvmMinimizing minimizing)
        Declares the strategy for reducing or eliminating non-initial Ion version markers, returning a new mutable builder if this is immutable. When null, IVMs are emitted as they are written.
        Parameters:
        minimizing - the IVM minimization strategy. Null indicates that all explicitly-written IVMs will be emitted.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.
        See Also:
        setIvmMinimizing(IonWriterBuilder.IvmMinimizing), getIvmMinimizing()

      • setLstMinimizing

        public void setLstMinimizing​(IonTextWriterBuilder.LstMinimizing minimizing)
        Sets the strategy for reducing or eliminating local symbol tables. By default, LST data is emitted as received or when necessary (for example, binary data will always collect and emit local symbols).
        Parameters:
        minimizing - the LST minimization strategy. Null indicates that LSTs will be emitted as received.
        Throws:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getLstMinimizing(), withLstMinimizing(LstMinimizing)

      • withLstMinimizing

        public final IonTextWriterBuilder withLstMinimizing​(IonTextWriterBuilder.LstMinimizing minimizing)
        Sets the strategy for reducing or eliminating local symbol tables. By default, LST data is emitted as received or when necessary (for example, binary data will always collect and emit local symbols).
        Parameters:
        minimizing - the LST minimization strategy. Null indicates that LSTs will be emitted as received.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.
        See Also:
        getLstMinimizing(), setLstMinimizing(LstMinimizing)

      • getLongStringThreshold

        public final int getLongStringThreshold()
        Gets the length beyond which string and clob content will be rendered as triple-quoted "long strings". At present, such content will only line-break on extant newlines.
        Returns:
        the threshold for printing triple-quoted strings and clobs. Zero means no limit.
        See Also:
        setLongStringThreshold(int), withLongStringThreshold(int)

      • setLongStringThreshold

        public void setLongStringThreshold​(int threshold)
        Sets the length beyond which string and clob content will be rendered as triple-quoted "long strings". At present, such content will only line-break on extant newlines.
        Parameters:
        threshold - the new threshold; zero means none.
        Throws:
        java.lang.UnsupportedOperationException - if this is immutable.
        See Also:
        getLongStringThreshold(), withLongStringThreshold(int)

      • withLongStringThreshold

        public final IonTextWriterBuilder withLongStringThreshold​(int threshold)
        Declares the length beyond which string and clob content will be rendered as triple-quoted "long strings". At present, such content will only line-break on extant newlines.
        Parameters:
        threshold - the new threshold; zero means none.
        Returns:
        this instance, if mutable; otherwise a mutable copy of this instance.
        See Also:
        getLongStringThreshold(), setLongStringThreshold(int)

      • getWriteTopLevelValuesOnNewLines

        public final boolean getWriteTopLevelValuesOnNewLines()
        Gets whether each top level value for standard printing should start on a new line. The default value is false. When false, the IonTextWriter will insert a single space character (U+0020) between top-level values. When pretty-printing, this setting is ignored; the pretty printer will always start top-level values on a new line.
        Returns:
        value indicating whether standard printing will insert a newline between top-level values
        See Also:
        setWriteTopLevelValuesOnNewLines(boolean), withWriteTopLevelValuesOnNewLines(boolean)

      • setWriteTopLevelValuesOnNewLines

        public void setWriteTopLevelValuesOnNewLines​(boolean writeTopLevelValuesOnNewLines)
        Sets whether each top level value for standard printing should start on a new line. The default value is false. When false, the IonTextWriter will insert a single space character (U+0020) between top-level values. When pretty-printing, this setting is ignored; the pretty printer will always start top-level values on a new line.
        Parameters:
        writeTopLevelValuesOnNewLines - value indicating whether standard printing will insert a newline between top-level values
        See Also:
        getWriteTopLevelValuesOnNewLines(), withWriteTopLevelValuesOnNewLines(boolean)

      • withWriteTopLevelValuesOnNewLines

        public final IonTextWriterBuilder withWriteTopLevelValuesOnNewLines​(boolean writeTopLevelValuesOnNewLines)
        Declares whether each top level value for standard printing should start on a new line. The default value is false. When false, the IonTextWriter will insert a single space character (U+0020) between top-level values. When pretty-printing, this setting is ignored; the pretty printer will always start top-level values on a new line.
        Parameters:
        writeTopLevelValuesOnNewLines - value indicating whether standard printing will insert a newline between top-level values
        See Also:
        getWriteTopLevelValuesOnNewLines(), setWriteTopLevelValuesOnNewLines(boolean)

      • build

        public abstract IonWriter build​(java.lang.Appendable out)
        Creates a new writer that will write text to the given output stream.

        If you have an OutputStream, you'll get better performance using IonWriterBuilder.build(OutputStream) as opposed to wrapping your stream in an Appendable and calling this method.

        Parameters:
        out - the stream that will receive Ion text data. Must not be null.
        Returns:
        a new IonWriter instance; not null.

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