IonBinaryWriterBuilder.java
/*
* Copyright 2007-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazon.ion.system;
import com.amazon.ion.IonCatalog;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonWriter;
import com.amazon.ion.SubstituteSymbolTableException;
import com.amazon.ion.SymbolTable;
import com.amazon.ion.impl._Private_IonBinaryWriterBuilder;
/**
* The builder for creating {@link IonWriter}s emitting the Ion binary format.
* <p>
* <b>WARNING:</b> This class should not be extended by code outside of
* this library.
* <p>
* Builders may be configured once and reused to construct multiple
* objects.
* <p>
* <b>Instances of this class are not not safe for use by multiple threads
* unless they are {@linkplain #immutable() immutable}.</b>
*
*/
public abstract class IonBinaryWriterBuilder
extends IonWriterBuilderBase<IonBinaryWriterBuilder>
{
private boolean myStreamCopyOptimized;
/** NOT FOR APPLICATION USE! */
protected IonBinaryWriterBuilder()
{
}
/** NOT FOR APPLICATION USE! */
protected IonBinaryWriterBuilder(IonBinaryWriterBuilder that)
{
super(that);
this.myStreamCopyOptimized = that.myStreamCopyOptimized;
}
/**
* The standard builder of binary writers, with all configuration
* properties having their default values.
*
* @return a new, mutable builder instance.
*/
public static IonBinaryWriterBuilder standard()
{
return _Private_IonBinaryWriterBuilder.standard();
}
//=========================================================================
// Overrides to fix the return type in JavaDocs
@Override
public abstract IonBinaryWriterBuilder copy();
@Override
public abstract IonBinaryWriterBuilder immutable();
@Override
public abstract IonBinaryWriterBuilder mutable();
@Override
public final IonBinaryWriterBuilder withCatalog(IonCatalog catalog)
{
return super.withCatalog(catalog);
}
@Override
public final IonBinaryWriterBuilder withImports(SymbolTable... imports)
{
return super.withImports(imports);
}
//=========================================================================
/**
* @return always {@link IonWriterBuilder.InitialIvmHandling#ENSURE}.
*/
@Override
public InitialIvmHandling getInitialIvmHandling()
{
return InitialIvmHandling.ENSURE;
}
// TODO Setting ivmMinimizing seems reasonable. Does the writer handle it?
/**
* @return always null.
*/
@Override
public IvmMinimizing getIvmMinimizing()
{
return null;
}
//=========================================================================
/**
* Gets the symbol table to use for encoded data.
* To avoid conflicts between different data streams, if the given instance
* is mutable, it will be copied when {@code build()} is called.
*
* @return a local or system symbol table.
* May be null, in which case the initial symbol table is that of
* {@code $ion_1_0}.
*
* @see #setInitialSymbolTable(SymbolTable)
* @see #withInitialSymbolTable(SymbolTable)
*/
public abstract SymbolTable getInitialSymbolTable();
/**
* Auto-flush enables automatic execution of flush operations during the write process. When auto-flush is enabled and a new block allocation becomes necessary while writing the top-level value, a new block will be allocated.
* The data writing process will then continue uninterrupted until the top-level value is complete. After completing the top-level value that crosses the block boundary, the flush operation will be executed.
* This feature optimizes performance of the writing of long data streams by reducing block allocations.
* Additionally, setting a larger block size can further tune performance when auto-flush is enabled.
* A larger block size leads to fewer block allocations and reduces the frequency of flush operations when auto-flush is enabled. {@link #withBlockSize(int) Here} is where you can set up the
* block size of write buffer.
* Auto-flush is disabled by default and the default block size is 32K.
* @param autoFlushEnabled A boolean parameter indicating whether this functionality is enabled or not.
*/
public abstract IonBinaryWriterBuilder withAutoFlushEnabled(boolean autoFlushEnabled);
/**
* Declares the symbol table to use for encoded data.
* To avoid conflicts between different data streams, if the given instance
* is mutable, it will be copied when {@code build()} is called.
* @param symtab must be a local or system symbol table.
* May be null, in which case the initial symbol table is that of
* {@code $ion_1_0}.
*
* @throws SubstituteSymbolTableException
* if any imported table is a substitute (see {@link SymbolTable}).
*
* @see #getInitialSymbolTable()
* @see #withInitialSymbolTable(SymbolTable)
*/
public abstract void setInitialSymbolTable(SymbolTable symtab);
/**
* Declares the symbol table to use for encoded data.
* To avoid conflicts between different data streams, if the given instance
* is mutable, it will be copied when {@code build()} is called.
*
* @param symtab must be a local or system symbol table.
* May be null, in which case the initial symbol table is that of
* {@code $ion_1_0}.
*
* @throws SubstituteSymbolTableException
* if any imported table is a substitute (see {@link SymbolTable}).
*/
public abstract
IonBinaryWriterBuilder withInitialSymbolTable(SymbolTable symtab);
/**
* Enables or disables writing local symbol tables that append symbols
* to the current symbol table. This functionality is disabled by default.
*/
public abstract void setLocalSymbolTableAppendEnabled(boolean enabled);
/**
* Enables writing local symbol tables that append symbols to the current
* symbol table. This functionality is disabled by default.
*/
public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendEnabled();
/**
* Disables writing local symbol tables that append symbols to the current
* symbol table. This functionality is disabled by default.
*/
public abstract IonBinaryWriterBuilder withLocalSymbolTableAppendDisabled();
/**
* Specify the block size for write buffer.
* @param size represent the specified block size in bytes.
* If this functionality is not set, the default block size is 32768 bytes.
*/
public abstract IonBinaryWriterBuilder withBlockSize(int size);
/**
* Enables or disables writing Binary32 (4-byte, single precision,
* IEEE-754) values for floats when there would be no loss in precision.
* By default Binary32 support is disabled to ensure the broadest
* compatibility with existing Ion implementations. Historically,
* implementations were only able to read Binary64 values.
* <p>
* When enabled, floats are evaluated for a possible loss of data at single
* precision. If the value can be represented in single precision without
* data loss, it is written as a 4-byte, Binary32 value. Floats which cannot
* be represented as single-precision values are written as 8-byte,
* Binary64 values (this is the legacy behavior for all floats, regardless
* of value).
*
* @param enabled {@code true} to enable writing 4-byte floats,
* {@code false} to always write 8-byte floats.
*
* @see IonBinaryWriterBuilder#withFloatBinary32Enabled
* @see IonBinaryWriterBuilder#withFloatBinary32Disabled
*/
public abstract void setIsFloatBinary32Enabled(boolean enabled);
/**
* Enables writing Binary32 (4-byte, single precision, IEEE-754) values
* for floats when there would be no loss in precision. By default Binary32
* support is disabled to ensure the broadest compatibility with existing
* Ion implementations. Historically, implementations were only able to read
* Binary64 values.
* <p>
* When enabled, floats are evaluated for a possible loss of data at single
* precision. If the value can be represented in single precision without
* data loss, it is written as a 4-byte, Binary32 value. Floats which
* cannot be represented as single-precision values are written as 8-byte,
* Binary64 values (this is the legacy behavior for all floats, regardless
* of value).
*
* @see IonBinaryWriterBuilder#setIsFloatBinary32Enabled(boolean)
* @see IonBinaryWriterBuilder#withFloatBinary32Disabled
*/
public abstract IonBinaryWriterBuilder withFloatBinary32Enabled();
/**
* Disables writing Binary32 (4-byte, single precision, IEEE-754) values for
* floats. This is the default behavior.
* <p>
* When disabled, floats are always written as 8-byte, Binary64 values
* regardless of value. This is the legacy behavior for all Ion binary
* writers and ensures the boarded compatibility with other Ion consumers.
*
* @see IonBinaryWriterBuilder#setIsFloatBinary32Enabled(boolean)
* @see IonBinaryWriterBuilder#withFloatBinary32Enabled
*/
public abstract IonBinaryWriterBuilder withFloatBinary32Disabled();
//=========================================================================
/**
* Indicates whether built writers may attempt to optimize
* {@link IonWriter#writeValue(IonReader)} by copying raw source data.
* By default, this property is false.
*
* @see #setStreamCopyOptimized(boolean)
* @see #withStreamCopyOptimized(boolean)
*/
public boolean isStreamCopyOptimized()
{
return myStreamCopyOptimized;
}
/**
* Declares whether built writers may attempt to optimize
* {@link IonWriter#writeValue(IonReader)} by copying raw source data.
* By default, this property is false.
* <p>
* <b>This feature is experimental! Please test thoroughly and report any
* issues.</b>
*
* @throws UnsupportedOperationException if this is immutable.
*
* @see #isStreamCopyOptimized()
* @see #withStreamCopyOptimized(boolean)
*/
public void setStreamCopyOptimized(boolean optimized)
{
mutationCheck();
myStreamCopyOptimized = optimized;
}
/**
* Declares whether built writers may attempt to optimize
* {@link IonWriter#writeValue(IonReader)} by copying raw source data,
* returning a new mutable builder if this is immutable.
* <p>
* <b>This feature is experimental! Please test thoroughly and report any
* issues.</b>
*
* @see #isStreamCopyOptimized()
* @see #setStreamCopyOptimized(boolean)
*/
public final
IonBinaryWriterBuilder withStreamCopyOptimized(boolean optimized)
{
IonBinaryWriterBuilder b = mutable();
b.setStreamCopyOptimized(optimized);
return b;
}
}