public abstract class IonTextWriterBuilder extends IonWriterBuilder
IonWriter
s 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.
IonWriter
s 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/issues/32 if you require it.
Modifier and Type | Class and Description |
---|---|
static class |
IonTextWriterBuilder.LstMinimizing
A strategy for minimizing the output of local symbol tables.
|
IonWriterBuilder.InitialIvmHandling, IonWriterBuilder.IvmMinimizing
Modifier and Type | Field and Description |
---|---|
static Charset |
ASCII
The
"US-ASCII" charset. |
static Charset |
UTF8
The
"UTF-8" charset. |
Modifier | Constructor and Description |
---|---|
protected |
IonTextWriterBuilder()
NOT FOR APPLICATION USE!
|
protected |
IonTextWriterBuilder(IonTextWriterBuilder that)
NOT FOR APPLICATION USE!
|
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.
|
build
public static final Charset ASCII
"US-ASCII"
charset.public static final Charset UTF8
"UTF-8"
charset.protected IonTextWriterBuilder()
protected IonTextWriterBuilder(IonTextWriterBuilder that)
public static IonTextWriterBuilder standard()
IonWriter
s, 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.public static IonTextWriterBuilder minimal()
withMinimalSystemData()
public static IonTextWriterBuilder pretty()
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.
withPrettyPrinting()
public static IonTextWriterBuilder json()
withJsonDowngrade()
public abstract IonTextWriterBuilder copy()
this
.public abstract IonTextWriterBuilder immutable()
public abstract IonTextWriterBuilder mutable()
public final IonTextWriterBuilder withCatalog(IonCatalog catalog)
IonWriter
,
returning a new mutable builder if this is immutable.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.getCatalog()
,
setCatalog(IonCatalog)
public final IonTextWriterBuilder withImports(SymbolTable... imports)
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
.
imports
- a sequence of shared symbol tables.
The first (and only the first) may be a system table.getImports()
,
setImports(SymbolTable...)
public final Charset getCharset()
setCharset(Charset)
,
withCharset(Charset)
public void setCharset(Charset charset)
ASCII
and UTF8
.charset
- may be null, denoting the default of UTF-8.UnsupportedOperationException
- if this is immutable.getCharset()
,
withCharset(Charset)
public final IonTextWriterBuilder withCharset(Charset charset)
ASCII
and UTF8
.charset
- may be null, denoting the default of UTF-8.getCharset()
,
setCharset(Charset)
public final IonTextWriterBuilder withCharsetAscii()
US-ASCII
.public final IonTextWriterBuilder withMinimalSystemData()
This is equivalent to:
public abstract IonTextWriterBuilder withPrettyPrinting()
The specifics of this configuration may change between releases of this library, so automated processes should not depend on the exact output formatting.
public abstract IonTextWriterBuilder withJsonDowngrade()
The specific conversions are as follows:
withMinimalSystemData()
.
null
.
public final IonWriterBuilder.InitialIvmHandling getInitialIvmHandling()
getInitialIvmHandling
in class IonWriterBuilder
null
) indicates that an initial IVM is
emitted if and only if it is received by the writer.setInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
,
withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
public void setInitialIvmHandling(IonWriterBuilder.InitialIvmHandling handling)
handling
- the initial IVM strategy.
Null indicates that explicitly-written IVMs will be emitted.UnsupportedOperationException
- if this is immutable.getInitialIvmHandling()
,
withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
public final IonTextWriterBuilder withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling handling)
handling
- the initial IVM strategy.
Null indicates that explicitly-written IVMs will be emitted.setInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
,
withInitialIvmHandling(IonWriterBuilder.InitialIvmHandling)
public final IonWriterBuilder.IvmMinimizing getIvmMinimizing()
This strategy does not affect handling of IVMs at the start of the
stream; that's the job of IonWriterBuilder.InitialIvmHandling
.
getIvmMinimizing
in class IonWriterBuilder
null
) indicates that no minimization occurs
and IVMs are emitted as received by the writer.setIvmMinimizing(IonWriterBuilder.IvmMinimizing)
,
withIvmMinimizing(IonWriterBuilder.IvmMinimizing)
public void setIvmMinimizing(IonWriterBuilder.IvmMinimizing minimizing)
minimizing
- the IVM minimization strategy.
Null indicates that all explicitly-written IVMs will be emitted.UnsupportedOperationException
- if this is immutable.getIvmMinimizing()
,
withIvmMinimizing(IonWriterBuilder.IvmMinimizing)
public final IonTextWriterBuilder withIvmMinimizing(IonWriterBuilder.IvmMinimizing minimizing)
minimizing
- the IVM minimization strategy.
Null indicates that all explicitly-written IVMs will be emitted.setIvmMinimizing(IonWriterBuilder.IvmMinimizing)
,
getIvmMinimizing()
public final IonTextWriterBuilder.LstMinimizing getLstMinimizing()
public void setLstMinimizing(IonTextWriterBuilder.LstMinimizing minimizing)
minimizing
- the LST minimization strategy.
Null indicates that LSTs will be emitted as received.UnsupportedOperationException
- if this is immutable.getLstMinimizing()
,
withLstMinimizing(LstMinimizing)
public final IonTextWriterBuilder withLstMinimizing(IonTextWriterBuilder.LstMinimizing minimizing)
minimizing
- the LST minimization strategy.
Null indicates that LSTs will be emitted as received.getLstMinimizing()
,
setLstMinimizing(LstMinimizing)
public final int getLongStringThreshold()
setLongStringThreshold(int)
,
withLongStringThreshold(int)
public void setLongStringThreshold(int threshold)
threshold
- the new threshold; zero means none.UnsupportedOperationException
- if this is immutable.getLongStringThreshold()
,
withLongStringThreshold(int)
public final IonTextWriterBuilder withLongStringThreshold(int threshold)
threshold
- the new threshold; zero means none.getLongStringThreshold()
,
setLongStringThreshold(int)
public abstract IonWriter build(Appendable out)
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.
out
- the stream that will receive Ion text data.
Must not be null.IonWriter
instance; not null
.protected void mutationCheck()
public final IonCatalog getCatalog()
IonWriter
.
The catalog is needed to resolve manually-written imports (not common).
By default, this property is null.setCatalog(IonCatalog)
,
withCatalog(IonCatalog)
public void setCatalog(IonCatalog catalog)
IonWriter
.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.UnsupportedOperationException
- if this is immutable.getCatalog()
,
withCatalog(IonCatalog)
public final SymbolTable[] getImports()
setImports(SymbolTable...)
,
withImports(SymbolTable...)
public void setImports(SymbolTable... imports)
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
.
imports
- a sequence of shared symbol tables.
The first (and only the first) may be a system table.UnsupportedOperationException
- if this is immutable.getImports()
,
withImports(SymbolTable...)