Package com.amazon.ion.system

Class IonTextWriterBuilder

java.lang.Object
com.amazon.ion.system.IonWriterBuilder
com.amazon.ion.system.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 Details

    • ASCII

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

    • UTF8

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

  • Constructor Details

    • IonTextWriterBuilder

      protected IonTextWriterBuilder()
      NOT FOR APPLICATION USE!

    • IonTextWriterBuilder

      protected IonTextWriterBuilder(IonTextWriterBuilder that)
      NOT FOR APPLICATION USE!

  • Method Details

    • 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

      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:

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

    • json

      public static IonTextWriterBuilder json()
      Creates a builder preconfigured for JSON compatibility.
      Returns:
      a new, mutable builder instance.
      See Also:

    • copy

      public abstract IonTextWriterBuilder copy()

    • immutable

      public abstract IonTextWriterBuilder immutable()

    • mutable

      public abstract IonTextWriterBuilder mutable()

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

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

    • getCharset

      public final 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

      public void setCharset(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:
      UnsupportedOperationException - if this is immutable.
      See Also:

    • withCharset

      public final IonTextWriterBuilder withCharset(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:

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

    • withMinimalSystemData

      public final IonTextWriterBuilder withMinimalSystemData()
      Declares that this builder should minimize system-level output (Ion version markers and local symbol tables).

      This is equivalent to:

      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.

    • getInitialIvmHandling

      public final IonWriterBuilder.InitialIvmHandling getInitialIvmHandling()
      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:
      the initial IVM strategy. The default value (null) indicates that an initial IVM is emitted if and only if it is received by the writer.
      See Also:

    • 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:
      UnsupportedOperationException - if this is immutable.
      See Also:

    • withInitialIvmHandling

      public final IonTextWriterBuilder withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling handling)
      Declares the strategy for emitting Ion version markers at the start of the stream, returning a new mutable builder if this is immutable. 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.
      Returns:
      this instance, if mutable; otherwise a mutable copy of this instance.
      See Also:

    • getIvmMinimizing

      public final IonWriterBuilder.IvmMinimizing getIvmMinimizing()
      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:
      the IVM minimizing strategy. The default value (null) indicates that no minimization occurs and IVMs are emitted as received by the writer.
      See Also:

    • 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:
      UnsupportedOperationException - if this is immutable.
      See Also:

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

    • getLstMinimizing

      public final IonTextWriterBuilder.LstMinimizing getLstMinimizing()
      Gets 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).
      See Also:

    • 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:
      UnsupportedOperationException - if this is immutable.
      See Also:

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

    • 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

      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:
      UnsupportedOperationException - if this is immutable.
      See Also:

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

    • getNewLineType

      public final IonTextWriterBuilder.NewLineType getNewLineType()
      Gets the character sequence that will be written as a line separator. The default is IonTextWriterBuilder.NewLineType.PLATFORM_DEPENDENT
      Returns:
      the character sequence to be written between top-level values; null means the default should be used.
      See Also:

    • setNewLineType

      public void setNewLineType(IonTextWriterBuilder.NewLineType newLineType)
      Sets the character sequence that will be written as a line separator. The default is IonTextWriterBuilder.NewLineType.PLATFORM_DEPENDENT
      Parameters:
      newLineType - the character sequence to be written between top-level values; null means the default should be used.
      Throws:
      UnsupportedOperationException - if this is immutable.
      See Also:

    • withNewLineType

      public final IonTextWriterBuilder withNewLineType(IonTextWriterBuilder.NewLineType newLineType)
      Declares the character sequence that will be written as a line separator. The default is IonTextWriterBuilder.NewLineType.PLATFORM_DEPENDENT
      Parameters:
      newLineType - the character sequence to be written between top-level values; null means the default should be used.
      Returns:
      this instance, if mutable; otherwise a mutable copy of this instance.
      See Also:

    • 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

      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:

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

    • build

      public abstract IonWriter build(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!

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