public class IonSystemBuilder extends Object
IonSystem
s.
Most applications will only have one or two system instances;
see IonSystem
for important constraints.
Builders may be configured once and reused to construct multiple
objects. They can be copied
to create a mutable
copy of a prototype (presumably for altering some property).
Instances of this class are not safe for use by multiple threads unless they are immutable.
The easiest way to get going is to use the standard()
builder:
IonSystem ion = IonSystemBuilder.standard().build();
However, most long-lived applications will want to provide a custom
IonCatalog
implementation rather than using the default
SimpleCatalog
. For example:
IonCatalog catalog = newCustomCatalog(); IonSystemBuilder b = IonSystemBuilder.standard().copy(); b.setCatalog(catalog); IonSystem ion = b.build();
Configuration properties follow the standard JavaBeans idiom in order to be friendly to dependency injection systems. They also provide alternative mutation methods that enable a more fluid style:
IonCatalog catalog = newCustomCatalog(); IonSystem ion = IonSystemBuilder.standard() .withCatalog(catalog) .build();
This builder provides the following configurable properties:
IonCatalog
used as a default when reading Ion
data. If null, each system will be built with a new
SimpleCatalog
.
Modifier and Type | Method and Description |
---|---|
IonSystem |
build()
Builds a new
IonSystem instance based on this builder's
configuration properties. |
IonSystemBuilder |
copy()
Creates a mutable copy of this builder.
|
IonCatalog |
getCatalog()
Gets the catalog to use when building an
IonSystem . |
IonReaderBuilder |
getReaderBuilder()
Gets the reader builder whose options will be used when building an
IonSystem . |
IonSystemBuilder |
immutable()
Returns an immutable builder configured exactly like this one.
|
boolean |
isStreamCopyOptimized()
Indicates whether built systems may attempt to optimize
IonWriter.writeValue(IonReader) by copying raw source data. |
IonSystemBuilder |
mutable()
Returns a mutable builder configured exactly like this one.
|
void |
setCatalog(IonCatalog catalog)
Sets the catalog to use when building an
IonSystem . |
void |
setReaderBuilder(IonReaderBuilder builder)
Sets the reader builder whose options will be used to use when building
an
IonSystem . |
void |
setStreamCopyOptimized(boolean optimized)
Declares whether built systems may attempt to optimize
IonWriter.writeValue(IonReader) by copying raw source data. |
static IonSystemBuilder |
standard()
The standard builder of
IonSystem s. |
IonSystemBuilder |
withCatalog(IonCatalog catalog)
Declares the catalog to use when building an
IonSystem ,
returning a new mutable builder if this is immutable. |
IonSystemBuilder |
withReaderBuilder(IonReaderBuilder builder)
Declares the reader builder whose options will be used to use when building
an
IonSystem , returning a new mutable builder if this is immutable. |
IonSystemBuilder |
withStreamCopyOptimized(boolean optimized)
Declares whether built systems may attempt to optimize
IonWriter.writeValue(IonReader) by copying raw source data,
returning a new mutable builder if this is immutable. |
public static IonSystemBuilder standard()
IonSystem
s.
See the class documentation for the standard configuration.
The returned instance is immutable.
public final IonSystemBuilder copy()
this
.public IonSystemBuilder immutable()
public IonSystemBuilder mutable()
public final IonCatalog getCatalog()
IonSystem
.
By default, this property is null.public final void setCatalog(IonCatalog catalog)
IonSystem
.catalog
- the catalog to use in built systems.
If null, each system will be built with a new SimpleCatalog
.UnsupportedOperationException
- if this is immutable.getCatalog()
,
withCatalog(IonCatalog)
,
IonSystem.getCatalog()
public final IonSystemBuilder withCatalog(IonCatalog catalog)
IonSystem
,
returning a new mutable builder if this is immutable.catalog
- the catalog to use in built systems.
If null, each system will be built with a new SimpleCatalog
.getCatalog()
,
setCatalog(IonCatalog)
,
IonSystem.getCatalog()
public final boolean isStreamCopyOptimized()
IonWriter.writeValue(IonReader)
by copying raw source data.
By default, this property is false.public final void setStreamCopyOptimized(boolean optimized)
IonWriter.writeValue(IonReader)
by copying raw source data.
By default, this property is false.
This feature is experimental! Please test thoroughly and report any issues.
UnsupportedOperationException
- if this is immutable.isStreamCopyOptimized()
,
withStreamCopyOptimized(boolean)
public final IonSystemBuilder withStreamCopyOptimized(boolean optimized)
IonWriter.writeValue(IonReader)
by copying raw source data,
returning a new mutable builder if this is immutable.
This feature is experimental! Please test thoroughly and report any issues.
public final IonReaderBuilder getReaderBuilder()
IonSystem
. By default, IonReaderBuilder.standard()
will
be used.public final void setReaderBuilder(IonReaderBuilder builder)
IonSystem
. The reader builder's catalog will never be used; the
catalog provided to setCatalog(IonCatalog)
or
withCatalog(IonCatalog)
will always be used instead.builder
- the reader builder to use in built systems.
If null, each system will be built with IonReaderBuilder.standard()
.UnsupportedOperationException
- if this is immutable.getReaderBuilder()
,
withReaderBuilder(IonReaderBuilder)
public final IonSystemBuilder withReaderBuilder(IonReaderBuilder builder)
IonSystem
, returning a new mutable builder if this is immutable.
The reader builder's catalog will never be used; the catalog provided to
setCatalog(IonCatalog)
or withCatalog(IonCatalog)
will
always be used instead.builder
- the reader builder to use in built systems.
If null, each system will be built with IonReaderBuilder.standard()
.getReaderBuilder()
,
setReaderBuilder(IonReaderBuilder)