IonTextWriterBuilder (Ion Java 1.3.0)

java.lang.Object
- software.amazon.ion.system.IonWriterBuilder
- - software.amazon.ion.system.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 amzn/ion-java#32 if you require it.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class IonTextWriterBuilder.LstMinimizing
A strategy for minimizing the output of local symbol tables.
- Nested classes/interfaces inherited from class software.amazon.ion.system.IonWriterBuilder
  IonWriterBuilder.InitialIvmHandling, IonWriterBuilder.IvmMinimizing

Nested Classes
Modifier and Type	Class and Description
`static class`	`IonTextWriterBuilder.LstMinimizing` A strategy for minimizing the output of local symbol tables.

Field Summary

Fields
Modifier and Type Field and Description

static Charset ASCII
The "US-ASCII" charset.

static Charset UTF8
The "UTF-8" charset.

Fields
Modifier and Type	Field and Description
`static Charset`	`ASCII` The `"US-ASCII"` charset.
`static Charset`	`UTF8` The `"UTF-8"` charset.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`IonTextWriterBuilder()` NOT FOR APPLICATION USE!
`protected`	`IonTextWriterBuilder(IonTextWriterBuilder that)` NOT FOR APPLICATION USE!

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract IonWriter`	`build(Appendable out)` Creates a new writer that will write text to the given output stream.
`abstract IonTextWriterBuilder`	`copy()` Creates a mutable copy of this builder.
`IonCatalog`	`getCatalog()` Gets the catalog to use when building an `IonWriter`.
`Charset`	`getCharset()` Gets the charset denoting the output encoding.
`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.
`IonWriterBuilder.IvmMinimizing`	`getIvmMinimizing()` Gets the strategy for eliminating Ion version markers mid-stream.
`int`	`getLongStringThreshold()` Gets the length beyond which string and clob content will be rendered as triple-quoted "long strings".
`IonTextWriterBuilder.LstMinimizing`	`getLstMinimizing()` Gets the strategy for reducing or eliminating local symbol tables.
`abstract IonTextWriterBuilder`	`immutable()` Returns an immutable builder configured exactly like this one.
`static IonTextWriterBuilder`	`json()` Creates a builder preconfigured for JSON compatibility.
`static IonTextWriterBuilder`	`minimal()` Creates a builder configured to minimize system data, eliminating local symbol tables and minimizing version markers.
`abstract IonTextWriterBuilder`	`mutable()` Returns a mutable builder configured exactly like this one.
`protected void`	`mutationCheck()` NOT FOR APPLICATION USE!
`static IonTextWriterBuilder`	`pretty()` Creates a builder preconfigured for basic pretty-printing.
`void`	`setCatalog(IonCatalog catalog)` Sets the catalog to use when building an `IonWriter`.
`void`	`setCharset(Charset charset)` Sets the charset denoting the output encoding.
`void`	`setImports(SymbolTable... imports)` Sets the shared symbol tables that will be used to construct the initial local symbol table.
`void`	`setInitialIvmHandling(IonWriterBuilder.InitialIvmHandling handling)` Sets the strategy for emitting Ion version markers at the start of the stream.
`void`	`setIvmMinimizing(IonWriterBuilder.IvmMinimizing minimizing)` Sets the strategy for reducing or eliminating non-initial Ion version markers.
`void`	`setLongStringThreshold(int threshold)` Sets the length beyond which string and clob content will be rendered as triple-quoted "long strings".
`void`	`setLstMinimizing(IonTextWriterBuilder.LstMinimizing minimizing)` Sets the strategy for reducing or eliminating local symbol tables.
`static IonTextWriterBuilder`	`standard()` The standard builder of text `IonWriter`s, with all configuration properties having their default values.
`IonTextWriterBuilder`	`withCatalog(IonCatalog catalog)` Declares the catalog to use when building an `IonWriter`, returning a new mutable builder if this is immutable.
`IonTextWriterBuilder`	`withCharset(Charset charset)` Declares the charset denoting the output encoding, returning a new mutable builder if this is immutable.
`IonTextWriterBuilder`	`withCharsetAscii()` Declares the output encoding to be `US-ASCII`.
`IonTextWriterBuilder`	`withImports(SymbolTable... imports)` Declares the imports to use when building an `IonWriter`, returning a new mutable builder if this is immutable.
`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.
`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.
`abstract IonTextWriterBuilder`	`withJsonDowngrade()` Declares that this builder should downgrade the writers' output to JSON compatibility.
`IonTextWriterBuilder`	`withLongStringThreshold(int threshold)` Declares the length beyond which string and clob content will be rendered as triple-quoted "long strings".
`IonTextWriterBuilder`	`withLstMinimizing(IonTextWriterBuilder.LstMinimizing minimizing)` Sets the strategy for reducing or eliminating local symbol tables.
`IonTextWriterBuilder`	`withMinimalSystemData()` Declares that this builder should minimize system-level output (Ion version markers and local symbol tables).
`abstract IonTextWriterBuilder`	`withPrettyPrinting()` Declares that this builder should use basic pretty-printing.

Methods inherited from class software.amazon.ion.system.IonWriterBuilder
build

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ASCII
```
public static final Charset ASCII
```
    The "US-ASCII" charset.
  - UTF8
```
public static final 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()
  - json
```
public static IonTextWriterBuilder json()
```
    Creates a builder preconfigured for JSON compatibility.
    
    Returns:
    
    a new, mutable builder instance.
    
    See Also:
    
    withJsonDowngrade()
  - copy
```
public abstract IonTextWriterBuilder copy()
```
    Creates a mutable copy of this builder.
    
    Returns:
    
    a new builder with the same configuration as this.
  - immutable
```
public abstract IonTextWriterBuilder immutable()
```
    Returns an immutable builder configured exactly like this one.
    
    Returns:
    
    this instance, if immutable; otherwise an immutable copy of this instance.
  - mutable
```
public abstract IonTextWriterBuilder mutable()
```
    Returns a mutable builder configured exactly like this one.
    
    Returns:
    
    this instance, if mutable; otherwise a mutable copy of this instance.
  - 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 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(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:
    
    getCharset(), withCharset(Charset)
  - 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:
    
    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.
  - 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(IonWriterBuilder.InitialIvmHandling), withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
  - 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:
    
    getInitialIvmHandling(), withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
  - 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:
    
    setInitialIvmHandling(IonWriterBuilder.InitialIvmHandling), withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
  - 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(IonWriterBuilder.IvmMinimizing), withIvmMinimizing(IonWriterBuilder.IvmMinimizing)
  - 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:
    
    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()
  - 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(LstMinimizing), withLstMinimizing(LstMinimizing)
  - 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:
    
    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:
    
    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)
  - 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(IonCatalog), withCatalog(IonCatalog)
  - 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:
    
    getCatalog(), withCatalog(IonCatalog)
  - 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(SymbolTable...), withImports(SymbolTable...)
  - 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:
    
    getImports(), withImports(SymbolTable...)

Class IonTextWriterBuilder

Auto-flushing

Nested Class Summary

Nested classes/interfaces inherited from class software.amazon.ion.system.IonWriterBuilder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class software.amazon.ion.system.IonWriterBuilder

Methods inherited from class java.lang.Object

Field Detail

ASCII

UTF8

Constructor Detail

IonTextWriterBuilder

IonTextWriterBuilder

Method Detail

standard

minimal

pretty

json

copy

immutable

mutable

withCatalog

withImports

getCharset

setCharset

withCharset

withCharsetAscii

withMinimalSystemData

withPrettyPrinting

withJsonDowngrade

getInitialIvmHandling

setInitialIvmHandling

withInitialIvmHandling

getIvmMinimizing

setIvmMinimizing

withIvmMinimizing

getLstMinimizing

setLstMinimizing

withLstMinimizing

getLongStringThreshold

setLongStringThreshold

withLongStringThreshold

build

mutationCheck

getCatalog

setCatalog

getImports

setImports