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.
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.
| Modifier and Type | Class and Description |
|---|---|
| public static enum | IonTextWriterBuilder.
A strategy for minimizing the output of local symbol tables. |
| public static enum | IonTextWriterBuilder.
Represents common new-line separators that are valid in Ion. |
| Modifier and Type | Field and Description |
|---|---|
| public static final Charset | ASCII
The |
| private Charset | |
| private IonWriterBuilder. | |
| private IonWriterBuilder. | |
| private int | |
| private IonTextWriterBuilder. | |
| private int | |
| private IonTextWriterBuilder. | |
| private boolean | |
| public static final Charset | UTF8
The |
| Access | Constructor and Description |
|---|---|
| protected | |
| protected |
| Modifier and Type | Method and Description |
|---|---|
| public abstract IonWriter | build(Appendable
the stream that will receive Ion text data.
Must not be null. out)Creates a new writer that will write text to the given output stream. |
| public abstract IonTextWriterBuilder | copy()
Implements abstract com. Creates a mutable copy of this builder. |
| public final Charset | Returns: may be null, denoting the default of UTF-8.Gets the charset denoting the output encoding. |
| public final 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.Implements abstract com. Gets the strategy for emitting Ion version markers at the start of the stream. |
| public final IonWriterBuilder. | Returns: the IVM minimizing strategy. The default value (null) indicates that no minimization occurs
and IVMs are emitted as received by the writer.Implements abstract com. Gets the strategy for eliminating Ion version markers mid-stream. |
| public final int | Returns: the threshold for printing triple-quoted strings and clobs. Zero means no limit.Gets the length beyond which string and clob content will be rendered as triple-quoted "long strings". |
| public final IonTextWriterBuilder. | |
| public final int | Returns: the currently configured maximum.Gets the maximum number of digits of fractional second precision allowed to be written for timestamp values. |
| public final IonTextWriterBuilder. | Returns: the character sequence to be written between top-level values; null means the default should be used.Gets the character sequence that will be written as a line separator. |
| public final boolean | Returns: value indicating whether standard printing will insert a newline between top-level valuesGets whether each top level value for standard printing should start on a new line. |
| public abstract IonTextWriterBuilder | immutable()
Implements abstract com. Returns an immutable builder configured exactly like this one. |
| public static IonTextWriterBuilder | Returns: a new, mutable builder instance.Creates a builder preconfigured for JSON compatibility. |
| public static IonTextWriterBuilder | Returns: a new, mutable builder instance.Creates a builder configured to minimize system data, eliminating local symbol tables and minimizing version markers. |
| public abstract IonTextWriterBuilder | mutable()
Implements abstract com. Returns a mutable builder configured exactly like this one. |
| public static IonTextWriterBuilder | Returns: a new, mutable builder instance.Creates a builder preconfigured for basic pretty-printing. |
| public void | setCharset(Charset
may be null, denoting the default of UTF-8. charset)Sets the charset denoting the output encoding. |
| public void | setInitialIvmHandling(IonWriterBuilder.
the initial IVM strategy.
Null indicates that explicitly-written IVMs will be emitted. handlingSets the strategy for emitting Ion version markers at the start of the stream. |
| public void | setIvmMinimizing(IonWriterBuilder.
the IVM minimization strategy.
Null indicates that all explicitly-written IVMs will be emitted. minimizingSets the strategy for reducing or eliminating non-initial Ion version markers. |
| public void | setLongStringThreshold(int
the new threshold; zero means none. threshold)Sets the length beyond which string and clob content will be rendered as triple-quoted "long strings". |
| public void | setLstMinimizing(IonTextWriterBuilder.
the LST minimization strategy.
Null indicates that LSTs will be emitted as received. minimizingSets the strategy for reducing or eliminating local symbol tables. |
| public void | setMaximumTimestampPrecisionDigits(int maximumTimestampPrecisionDigits)
Sets the maximum number of digits of fractional second precision allowed to be written for timestamp values. |
| public void | setNewLineType(IonTextWriterBuilder.
the character sequence to be written between top-level values; null means the default should be used. newLineTypeSets the character sequence that will be written as a line separator. |
| public void | setWriteTopLevelValuesOnNewLines(boolean
value indicating whether standard printing will insert a newline between top-level values writeTopLevelValuesOnNewLines)Sets whether each top level value for standard printing should start on a new line. |
| public static IonTextWriterBuilder | |
| public final IonTextWriterBuilder | withCatalog(IonCatalog
the catalog to use in built writers.
If null, the writer will be unable to resolve manually-written imports
and may throw an exception. catalog)Overrides com. Declares the catalog to use when building an |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.may be null, denoting the default of UTF-8. charset)Declares the charset denoting the output encoding, returning a new mutable builder if this is immutable. |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.Declares the output encoding to be |
| public final IonTextWriterBuilder | withImports(SymbolTable...
a sequence of shared symbol tables.
The first (and only the first) may be a system table. imports)Overrides com. Declares the imports to use when building an |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.the initial IVM strategy.
Null indicates that explicitly-written IVMs will be emitted. handlingDeclares the strategy for emitting Ion version markers at the start of the stream, returning a new mutable builder if this is immutable. |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.the IVM minimization strategy.
Null indicates that all explicitly-written IVMs will be emitted. minimizingDeclares the strategy for reducing or eliminating non-initial Ion version markers, returning a new mutable builder if this is immutable. |
| public abstract IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.Declares that this builder should downgrade the writers' output to JSON compatibility. |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.the new threshold; zero means none. threshold)Declares the length beyond which string and clob content will be rendered as triple-quoted "long strings". |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.the LST minimization strategy.
Null indicates that LSTs will be emitted as received. minimizingSets the strategy for reducing or eliminating local symbol tables. |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.Sets the maximum number of digits of fractional second precision allowed to be written for timestamp values. |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.Declares that this builder should minimize system-level output (Ion version markers and local symbol tables). |
| public final IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.the character sequence to be written between top-level values; null means the default should be used. newLineTypeDeclares the character sequence that will be written as a line separator. |
| public abstract IonTextWriterBuilder | Returns: this instance, if mutable; otherwise a mutable copy of this instance.Declares that this builder should use basic pretty-printing. |
| public final IonTextWriterBuilder | withWriteTopLevelValuesOnNewLines(boolean
value indicating whether standard printing will insert a newline between top-level values writeTopLevelValuesOnNewLines)Declares whether each top level value for standard printing should start on a new line. |
| ASCII | back to summary |
|---|---|
| public static final Charset ASCII The | |
| myCharset | back to summary |
|---|---|
| private Charset myCharset | |
| myInitialIvmHandling | back to summary |
|---|---|
| private IonWriterBuilder. | |
| myIvmMinimizing | back to summary |
|---|---|
| private IonWriterBuilder. | |
| myLongStringThreshold | back to summary |
|---|---|
| private int myLongStringThreshold | |
| myLstMinimizing | back to summary |
|---|---|
| private IonTextWriterBuilder. | |
| myMaximumTimestampPrecisionDigits | back to summary |
|---|---|
| private int myMaximumTimestampPrecisionDigits | |
| myNewLineType | back to summary |
|---|---|
| private IonTextWriterBuilder. | |
| myTopLevelValuesOnNewLines | back to summary |
|---|---|
| private boolean myTopLevelValuesOnNewLines | |
| UTF8 | back to summary |
|---|---|
| public static final Charset UTF8 The | |
| IonTextWriterBuilder | back to summary |
|---|---|
| protected IonTextWriterBuilder() NOT FOR APPLICATION USE! | |
| IonTextWriterBuilder | back to summary |
|---|---|
| protected IonTextWriterBuilder(IonTextWriterBuilder that) NOT FOR APPLICATION USE! | |
| build | back to summary |
|---|---|
| public abstract IonWriter build(Appendable out) Creates a new writer that will write text to the given output stream.
If you have an
| |
| copy | back to summary |
|---|---|
| public abstract IonTextWriterBuilder copy() Implements abstract com. Doc from com. Creates a mutable copy of this builder.
| |
| getCharset | back to summary |
|---|---|
| public final Charset getCharset() Gets the charset denoting the output encoding. Only ASCII and UTF-8 are supported.
| |
| getInitialIvmHandling | back to summary |
|---|---|
| public final IonWriterBuilder. Implements abstract com. Doc from com. 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).
| |
| getIvmMinimizing | back to summary |
|---|---|
| public final IonWriterBuilder. Implements abstract com. Doc from com. 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
| |
| getLongStringThreshold | back to summary |
|---|---|
| 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.
| |
| getLstMinimizing | back to summary |
|---|---|
| public final IonTextWriterBuilder. 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). | |
| getMaximumTimestampPrecisionDigits | back to summary |
|---|---|
| public final int getMaximumTimestampPrecisionDigits() Gets the maximum number of digits of fractional second precision allowed to be written for timestamp values.
| |
| getNewLineType | back to summary |
|---|---|
| public final IonTextWriterBuilder. Gets the character sequence that will be written as a line separator.
The default is
| |
| getWriteTopLevelValuesOnNewLines | back to summary |
|---|---|
| public final boolean getWriteTopLevelValuesOnNewLines() Gets whether each top level value for standard printing should start on a new line. The default value is
| |
| immutable | back to summary |
|---|---|
| public abstract IonTextWriterBuilder immutable() Implements abstract com. Doc from com. Returns an immutable builder configured exactly like this one.
| |
| json | back to summary |
|---|---|
| public static IonTextWriterBuilder json() Creates a builder preconfigured for JSON compatibility.
| |
| minimal | back to summary |
|---|---|
| public static IonTextWriterBuilder minimal() Creates a builder configured to minimize system data, eliminating local symbol tables and minimizing version markers.
| |
| mutable | back to summary |
|---|---|
| public abstract IonTextWriterBuilder mutable() Implements abstract com. Doc from com. Returns a mutable builder configured exactly like this one.
| |
| pretty | back to summary |
|---|---|
| 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.
| |
| setCharset | back to summary |
|---|---|
| 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
| |
| setInitialIvmHandling | back to summary |
|---|---|
| public void setInitialIvmHandling(IonWriterBuilder. 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).
| |
| setIvmMinimizing | back to summary |
|---|---|
| public void setIvmMinimizing(IonWriterBuilder. Sets the strategy for reducing or eliminating non-initial Ion version markers. When null, IVMs are emitted as they are written.
| |
| setLongStringThreshold | back to summary |
|---|---|
| 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.
| |
| setLstMinimizing | back to summary |
|---|---|
| public void setLstMinimizing(IonTextWriterBuilder. 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).
| |
| setMaximumTimestampPrecisionDigits | back to summary |
|---|---|
| public void setMaximumTimestampPrecisionDigits(int maximumTimestampPrecisionDigits) Sets the maximum number of digits of fractional second precision allowed to be written for timestamp values.
Default: | |
| setNewLineType | back to summary |
|---|---|
| public void setNewLineType(IonTextWriterBuilder. Sets the character sequence that will be written as a line separator.
The default is
| |
| setWriteTopLevelValuesOnNewLines | back to summary |
|---|---|
| public void setWriteTopLevelValuesOnNewLines(boolean writeTopLevelValuesOnNewLines) Sets whether each top level value for standard printing should start on a new line. The default value is
| |
| standard | back to summary |
|---|---|
| public static IonTextWriterBuilder standard() The standard builder of text
| |
| withCatalog | back to summary |
|---|---|
| public final IonTextWriterBuilder withCatalog(IonCatalog catalog) Overrides com. Doc from com. Declares the catalog to use when building an
| |
| withCharset | back to summary |
|---|---|
| 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
| |
| withCharsetAscii | back to summary |
|---|---|
| public final IonTextWriterBuilder withCharsetAscii() Declares the output encoding to be
| |
| withImports | back to summary |
|---|---|
| public final IonTextWriterBuilder withImports(SymbolTable... imports) Overrides com. Doc from com. Declares the imports to use when building an
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
| |
| withInitialIvmHandling | back to summary |
|---|---|
| public final IonTextWriterBuilder withInitialIvmHandling(IonWriterBuilder. 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).
| |
| withIvmMinimizing | back to summary |
|---|---|
| public final IonTextWriterBuilder withIvmMinimizing(IonWriterBuilder. 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.
| |
| withJsonDowngrade | back to summary |
|---|---|
| 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:
| |
| withLongStringThreshold | back to summary |
|---|---|
| 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.
| |
| withLstMinimizing | back to summary |
|---|---|
| public final IonTextWriterBuilder withLstMinimizing(IonTextWriterBuilder. 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).
| |
| withMaximumTimestampPrecisionDigits | back to summary |
|---|---|
| public final IonTextWriterBuilder withMaximumTimestampPrecisionDigits(int maximumTimestampPrecisionDigits) Sets the maximum number of digits of fractional second precision allowed to be written for timestamp values.
Default:
| |
| withMinimalSystemData | back to summary |
|---|---|
| public final IonTextWriterBuilder withMinimalSystemData() Declares that this builder should minimize system-level output (Ion version markers and local symbol tables). This is equivalent to:
| |
| withNewLineType | back to summary |
|---|---|
| public final IonTextWriterBuilder withNewLineType(IonTextWriterBuilder. Declares the character sequence that will be written as a line separator.
The default is
| |
| withPrettyPrinting | back to summary |
|---|---|
| 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.
| |
| withWriteTopLevelValuesOnNewLines | back to summary |
|---|---|
| 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
| |
| Modifier and Type | Field and Description |
|---|---|
| public static final IonTextWriterBuilder. | EVERYTHING
Discards everything, collapsing the LST to an IVM. |
| public static final IonTextWriterBuilder. | LOCALS
Discards local symbols, retains imports. |
| Access | Constructor and Description |
|---|---|
| private |
| Modifier and Type | Method and Description |
|---|---|
| public static IonTextWriterBuilder. | |
| public static IonTextWriterBuilder. |
| EVERYTHING | back to summary |
|---|---|
| public static final IonTextWriterBuilder. Discards everything, collapsing the LST to an IVM.
If | |
| LOCALS | back to summary |
|---|---|
| public static final IonTextWriterBuilder. Discards local symbols, retains imports. | |
| LstMinimizing | back to summary |
|---|---|
| private LstMinimizing() | |
| valueOf | back to summary |
|---|---|
| public static IonTextWriterBuilder. | |
| values | back to summary |
|---|---|
| public static IonTextWriterBuilder. | |
NEL) will result in printing invalid Ion.
| Modifier and Type | Field and Description |
|---|---|
| private final CharSequence | |
| public static final IonTextWriterBuilder. | CRLF
A carriage return and linefeed ( |
| public static final IonTextWriterBuilder. | LF
A single linefeed ( |
| public static final IonTextWriterBuilder. | PLATFORM_DEPENDENT
The new-line separator specified in the "line.separator" system property. |
| Access | Constructor and Description |
|---|---|
| private |
| Modifier and Type | Method and Description |
|---|---|
| public CharSequence | |
| public static IonTextWriterBuilder. | |
| public static IonTextWriterBuilder. |
| charSequence | back to summary |
|---|---|
| private final CharSequence charSequence | |
| CRLF | back to summary |
|---|---|
| public static final IonTextWriterBuilder. A carriage return and linefeed ( | |
| LF | back to summary |
|---|---|
| public static final IonTextWriterBuilder. A single linefeed ( | |
| PLATFORM_DEPENDENT | back to summary |
|---|---|
| public static final IonTextWriterBuilder. The new-line separator specified in the "line.separator" system property. Using this will result in writing invalid Ion if the platform uses anything other than CR and/or LF as the line separator and the IonTextWriter is configured to use pretty printing or to write each top-level value on a separate line. | |
| NewLineType | back to summary |
|---|---|
| private NewLineType(CharSequence cs) | |
| getCharSequence | back to summary |
|---|---|
| public CharSequence getCharSequence() | |
| valueOf | back to summary |
|---|---|
| public static IonTextWriterBuilder. | |
| values | back to summary |
|---|---|
| public static IonTextWriterBuilder. | |