IonSystemBuilder (ion-java 1.11.4 API)

java.lang.Object
- com.amazon.ion.system.IonSystemBuilder

```
public class IonSystemBuilder
extends java.lang.Object
```
The builder for creating IonSystems. 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();
```
Configuration Properties

This builder provides the following configurable properties:
- catalog: The IonCatalog used as a default when reading Ion data. If null, each system will be built with a new SimpleCatalog.
- streamCopyOptimized: When true, this enables optimizations when copying data between two Ion streams. For example, in some cases raw binary-encoded Ion can be copied directly from the input to the output. This can have significant performance benefits when the appropriate conditions are met. This feature is experimental! Please test thoroughly and report any issues.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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.

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

- Method Detail
  - standard
```
public static IonSystemBuilder standard()
```
    The standard builder of IonSystems. See the class documentation for the standard configuration.
    The returned instance is immutable.
  - copy
```
public final IonSystemBuilder copy()
```
    Creates a mutable copy of this builder.
    
    Returns:
    
    a new builder with the same configuration as this.
  - immutable
```
public IonSystemBuilder immutable()
```
    Returns an immutable builder configured exactly like this one.
    
    Returns:
    
    this instance, if immutable; otherwise an immutable copy of this instance.
  - mutable
```
public IonSystemBuilder mutable()
```
    Returns a mutable builder configured exactly like this one.
    
    Returns:
    
    this instance, if mutable; otherwise a mutable copy of this instance.
  - getCatalog
```
public final IonCatalog getCatalog()
```
    Gets the catalog to use when building an IonSystem. By default, this property is null.
    
    See Also:
    
    setCatalog(IonCatalog), withCatalog(IonCatalog), IonSystem.getCatalog()
  - setCatalog
```
public final void setCatalog(IonCatalog catalog)
```
    Sets the catalog to use when building an IonSystem.
    
    Parameters:
    
    catalog - the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this is immutable.
    
    See Also:
    
    getCatalog(), withCatalog(IonCatalog), IonSystem.getCatalog()
  - withCatalog
```
public final IonSystemBuilder withCatalog(IonCatalog catalog)
```
    Declares the catalog to use when building an IonSystem, returning a new mutable builder if this is immutable.
    
    Parameters:
    
    catalog - the catalog to use in built systems. If null, each system will be built with a new SimpleCatalog.
    
    See Also:
    
    getCatalog(), setCatalog(IonCatalog), IonSystem.getCatalog()
  - isStreamCopyOptimized
```
public final boolean isStreamCopyOptimized()
```
    Indicates whether built systems may attempt to optimize IonWriter.writeValue(IonReader) by copying raw source data. By default, this property is false.
    
    See Also:
    
    setStreamCopyOptimized(boolean), withStreamCopyOptimized(boolean)
  - setStreamCopyOptimized
```
public final void setStreamCopyOptimized(boolean optimized)
```
    Declares whether built systems may attempt to optimize 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.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this is immutable.
    
    See Also:
    
    isStreamCopyOptimized(), withStreamCopyOptimized(boolean)
  - withStreamCopyOptimized
```
public final 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.
    This feature is experimental! Please test thoroughly and report any issues.
    
    See Also:
    
    isStreamCopyOptimized(), setStreamCopyOptimized(boolean)
  - getReaderBuilder
```
public final IonReaderBuilder getReaderBuilder()
```
    Gets the reader builder whose options will be used when building an IonSystem. By default, IonReaderBuilder.standard() will be used.
    
    See Also:
    
    setReaderBuilder(IonReaderBuilder), withReaderBuilder(IonReaderBuilder)
  - setReaderBuilder
```
public final void setReaderBuilder(IonReaderBuilder builder)
```
    Sets the reader builder whose options will be used to use when building an IonSystem. The reader builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.
    
    Parameters:
    
    builder - the reader builder to use in built systems. If null, each system will be built with IonReaderBuilder.standard().
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this is immutable.
    
    See Also:
    
    getReaderBuilder(), withReaderBuilder(IonReaderBuilder)
  - withReaderBuilder
```
public final 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. The reader builder's catalog will never be used; the catalog provided to setCatalog(IonCatalog) or withCatalog(IonCatalog) will always be used instead.
    
    Parameters:
    
    builder - the reader builder to use in built systems. If null, each system will be built with IonReaderBuilder.standard().
    
    See Also:
    
    getReaderBuilder(), setReaderBuilder(IonReaderBuilder)
  - build
```
public final IonSystem build()
```
    Builds a new IonSystem instance based on this builder's configuration properties.

Class IonSystemBuilder

Configuration Properties

Method Summary

Methods inherited from class java.lang.Object

Method Detail

standard

copy

immutable

mutable

getCatalog

setCatalog

withCatalog

isStreamCopyOptimized

setStreamCopyOptimized

withStreamCopyOptimized

getReaderBuilder

setReaderBuilder

withReaderBuilder

build