Package com.amazon.ion.impl

Class _Private_IonBinaryWriterImpl

java.lang.Object

com.amazon.ion.impl._Private_IonWriterBase

com.amazon.ion.impl._Private_IonBinaryWriterImpl

All Implemented Interfaces:

Faceted, _Private_IonWriter, _Private_ListWriter, _Private_ReaderWriter, IonBinaryWriter, IonWriter, java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

@Deprecated
public final class _Private_IonBinaryWriterImpl
extends _Private_IonWriterBase
implements IonBinaryWriter

Deprecated.

NOT FOR APPLICATION USE!

Adapts the binary IonWriter implementation to the deprecated IonBinaryWriter interface.

Field Summary

Fields inherited from class com.amazon.ion.impl._Private_IonWriterBase

ERROR_MISSING_FIELD_NAME

Method Summary

Modifier and Type	Method	Description
void	addTypeAnnotation(java.lang.String annotation)	Adds a given string to the list of pending annotations.
int	byteSize()	Deprecated. Gets the size in bytes of this binary data.
void	close()	Closes this stream and releases any system resources associated with it.
void	finish()	Indicates that writing is completed and all buffered data should be written and flushed as if this were the end of the Ion data stream.
void	flush()	Flushes this writer by writing any buffered output to the underlying output target without finalizing the stream's local symbol table.
byte[]	getBytes()	Deprecated. Copies the current contents of this writer as a new byte array holding Ion binary-encoded data.
int	getBytes(byte[] bytes, int offset, int len)	Deprecated. Copies the current contents of the writer to a given byte array array.
IonCatalog	getCatalog()	Mostly for testing at this point, but could be useful public API.
int	getDepth()	Returns the current depth of containers the writer is at.
SymbolTable	getSymbolTable()	Gets the symbol table that is currently in use by the writer.
boolean	isFieldNameSet()	Returns true if the field name has been set either through setFieldName or setFieldId.
boolean	isInStruct()	Determines whether values are being written as fields of a struct.
boolean	isStreamCopyOptimized()	Indicates whether the writer is stream copy optimized through IonWriter.writeValue(com.amazon.ion.IonReader).
void	setFieldName(java.lang.String name)	Sets the pending field name to the given text.
void	setFieldNameSymbol(SymbolToken name)	Sets the pending field name to the given token.
void	setSymbolTable(SymbolTable symbols)	Sets the symbol table to use for encoding to be the passed in symbol table.
void	setTypeAnnotations(java.lang.String... annotations)	Sets the full list of pending annotations to the given text symbols.
void	setTypeAnnotationSymbols(SymbolToken... annotations)	Sets the full list of pending annotations to the given symbols.
void	stepIn(IonType containerType)	Writes the beginning of a non-null container (list, sexp, or struct).
void	stepOut()	Writes the end of the current container, returning this writer to the context of parent container.
void	writeBlob(byte[] value, int start, int len)	Writes a portion of the byte array out as an IonBlob value.
void	writeBool(boolean value)	writes a non-null boolean value (true or false) as an IonBool to output.
void	writeBoolList(boolean[] values)
int	writeBytes(java.io.OutputStream userstream)	Deprecated. Writes the current contents of the writer to the output stream.
void	writeClob(byte[] value, int start, int len)	Writes a portion of the byte array out as an IonClob value.
void	writeDecimal(java.math.BigDecimal value)	Writes a BigDecimal value as an Ion decimal.
void	writeFloat(double value)	writes a 64 bit binary floating point value, a Java double, as an IonFloat.
void	writeFloatList(double[] values)
void	writeFloatList(float[] values)
void	writeInt(int value)
void	writeInt(long value)	writes a signed 64 bit value, a Java long, as an IonInt.
void	writeInt(java.math.BigInteger value)	writes a BigInteger value as an IonInt.
void	writeIntList(byte[] values)
void	writeIntList(int[] values)
void	writeIntList(long[] values)
void	writeIntList(short[] values)
void	writeIonVersionMarker()	Write an Ion version marker symbol to the output.
void	writeNull(IonType type)	Writes a null value of a specified Ion type.
void	writeString(java.lang.String value)	Writes a String as an Ion string.
void	writeStringList(java.lang.String[] values)
void	writeSymbol(java.lang.String value)	Writes the text of an Ion symbol value.
void	writeTimestamp(Timestamp value)	Writes a timestamp value.
void	writeValue(IonReader reader)	Overrides can optimize special cases.

Methods inherited from class com.amazon.ion.impl._Private_IonWriterBase

asFacet, pop_passed_symbol_table, writeBlob, writeClob, writeFloat, writeNull, writeSymbolToken, writeTimestampUTC, writeValue, writeValues

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.amazon.ion.facet.Faceted

asFacet

Methods inherited from interface com.amazon.ion.IonWriter

addTypeAnnotation, close, finish, flush, getSymbolTable, isInStruct, setFieldName, setFieldNameSymbol, setTypeAnnotations, setTypeAnnotationSymbols, stepIn, stepOut, writeBlob, writeBlob, writeBool, writeClob, writeClob, writeDecimal, writeFloat, writeInt, writeInt, writeNull, writeNull, writeString, writeSymbol, writeSymbolToken, writeTimestamp, writeTimestampUTC, writeValue, writeValue, writeValues

Method Detail

byteSize

public int byteSize()

Deprecated.

Description copied from interface: IonBinaryWriter

Gets the size in bytes of this binary data. This is generally needed before calling IonBinaryWriter.getBytes() or IonBinaryWriter.getBytes(byte[], int, int).

Specified by:

byteSize in interface IonBinaryWriter

Returns:

the size in bytes.

getBytes

public byte[] getBytes()
                throws java.io.IOException

Deprecated.

Description copied from interface: IonBinaryWriter

Copies the current contents of this writer as a new byte array holding Ion binary-encoded data. This allocates an array of the size needed to exactly hold the output and copies the entire value to it.

Specified by:

getBytes in interface IonBinaryWriter

Returns:

the byte array with the writers output

Throws:

java.io.IOException

getBytes

public int getBytes(byte[] bytes,
                    int offset,
                    int len)
             throws java.io.IOException

Deprecated.

Description copied from interface: IonBinaryWriter

Copies the current contents of the writer to a given byte array array. This starts writing to the array at offset and writes up to maxlen bytes. If this writer is not able to stop in the middle of its work this may overwrite the array and later throw and exception.

Specified by:

getBytes in interface IonBinaryWriter

Parameters:

bytes - users byte array to write into

offset - initial offset in the array to write into

len - maximum number of bytes to write

Returns:

number of bytes written

Throws:

java.io.IOException

writeBytes

public int writeBytes(java.io.OutputStream userstream)
               throws java.io.IOException

Deprecated.

Description copied from interface: IonBinaryWriter

Writes the current contents of the writer to the output stream. This is only valid if the writer is not in the middle of writing a container.

Specified by:

writeBytes in interface IonBinaryWriter

Parameters:

userstream - OutputStream to write the bytes to

Returns:

int length of bytes written

Throws:

java.io.IOException

isStreamCopyOptimized

public boolean isStreamCopyOptimized()

Description copied from interface: _Private_IonWriter

Indicates whether the writer is stream copy optimized through IonWriter.writeValue(com.amazon.ion.IonReader).

Specified by:

isStreamCopyOptimized in interface _Private_IonWriter

Overrides:

isStreamCopyOptimized in class _Private_IonWriterBase

writeValue

public void writeValue(IonReader reader)
                throws java.io.IOException

Description copied from class: _Private_IonWriterBase

Overrides can optimize special cases.

Specified by:

writeValue in interface IonWriter

Overrides:

writeValue in class _Private_IonWriterBase

Throws:

java.io.IOException

writeBoolList

public void writeBoolList(boolean[] values)
                   throws java.io.IOException

Specified by:

writeBoolList in interface _Private_ListWriter

Throws:

java.io.IOException

writeFloatList

public void writeFloatList(float[] values)
                    throws java.io.IOException

Specified by:

writeFloatList in interface _Private_ListWriter

Throws:

java.io.IOException

writeFloatList

public void writeFloatList(double[] values)
                    throws java.io.IOException

Specified by:

writeFloatList in interface _Private_ListWriter

Throws:

java.io.IOException

writeIntList

public void writeIntList(byte[] values)
                  throws java.io.IOException

Specified by:

writeIntList in interface _Private_ListWriter

Throws:

java.io.IOException

writeIntList

public void writeIntList(short[] values)
                  throws java.io.IOException

Specified by:

writeIntList in interface _Private_ListWriter

Throws:

java.io.IOException

writeIntList

public void writeIntList(int[] values)
                  throws java.io.IOException

Specified by:

writeIntList in interface _Private_ListWriter

Throws:

java.io.IOException

writeIntList

public void writeIntList(long[] values)
                  throws java.io.IOException

Specified by:

writeIntList in interface _Private_ListWriter

Throws:

java.io.IOException

writeStringList

public void writeStringList(java.lang.String[] values)
                     throws java.io.IOException

Specified by:

writeStringList in interface _Private_ListWriter

Throws:

java.io.IOException

getCatalog

public IonCatalog getCatalog()

Description copied from interface: _Private_IonWriter

Mostly for testing at this point, but could be useful public API.

Specified by:

getCatalog in interface _Private_IonWriter

getDepth

public int getDepth()

Description copied from class: _Private_IonWriterBase

Returns the current depth of containers the writer is at. This is 0 if the writer is at top-level.

Specified by:

getDepth in interface _Private_IonWriter

Specified by:

getDepth in class _Private_IonWriterBase

Returns:

int depth of container nesting

isInStruct

public boolean isInStruct()

Description copied from interface: IonWriter

Determines whether values are being written as fields of a struct. This is especially useful when it is not clear whether field names need to be written or not.

Specified by:

isInStruct in interface IonWriter

Returns:

true when the parent is a struct.

flush

public void flush()
           throws java.io.IOException

Description copied from interface: IonWriter

Flushes this writer by writing any buffered output to the underlying output target without finalizing the stream's local symbol table.

For some implementations this may have no effect even when some data is buffered, because it's not always possible to fully write partial data. In particular, when writing binary Ion data, Ion's length-prefixed encoding requires a complete top-level value to be written at once.

If localSymbolTableAppend is enabled (see IonBinaryWriterBuilder.withLocalSymbolTableAppendEnabled()), this feature can be used to flush buffered data before writing more values without subsequently having to redeclare the current local symbol table. Applications that produce long streams of binary Ion may wish to flush occasionally to relieve memory pressure, then continue writing data using the same local symbol table. The symbol table will be appended with newly-encountered symbols as necessary.

Specified by:

flush in interface java.io.Flushable

Specified by:

flush in interface IonWriter

Throws:

java.io.IOException - if thrown by the underlying output target.

See Also:

IonWriter.finish()

close

public void close()
           throws java.io.IOException

Description copied from interface: IonWriter

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

If the cursor is between top-level values, this method will IonWriter.finish() before closing the underlying output stream. If not, the resulting data may be incomplete and invalid Ion.

In other words: unless you're recovering from a failure condition, don't close the writer until you've stepped-out back to the starting level.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface IonWriter

Throws:

java.io.IOException - if thrown by the underlying output target.

See Also:

IonWriter.finish()

finish

public final void finish()
                  throws java.io.IOException

Description copied from interface: IonWriter

Indicates that writing is completed and all buffered data should be written and flushed as if this were the end of the Ion data stream. For example, an Ion binary writer will finalize any local symbol table, write all top-level values, and then flush.

This method may only be called when all top-level values are completely written and stepped-out.

Implementations should allow the application to continue writing further top-level values following the semantics for concatenating Ion data streams. If another top-level value is written, the result must behave as if it were preceded by an Ion version marker, resetting the stream context as if this were a new stream. (Whether or not an IVM is written may depend upon the writer's configuration; see IvmMinimizing.)

This feature can be used to flush buffered data and reset the local symbol table before writing more values. Applications that produce long streams of binary Ion may wish to finish occasionally to relieve memory pressure, then continue writing data using a new local symbol table. This is particularly useful for streams that contain an ever-growing number of unique symbols to avoid unbounded growth of the symbol table, which may degrade performance and bloat the encoding. Applications that produce long streams with a limited number of unique symbols should enable localSymbolTableAppend (see IonBinaryWriterBuilder.withLocalSymbolTableAppendEnabled()) and IonWriter.flush() instead to avoid re-declaring the local symbol table unnecessarily.

Specified by:

finish in interface IonWriter

Throws:

java.io.IOException - if thrown by the underlying output target.

See Also:

IonWriter.flush(), IonWriter.close()

setSymbolTable

public final void setSymbolTable(SymbolTable symbols)
                          throws java.io.IOException

Description copied from class: _Private_IonWriterBase

Sets the symbol table to use for encoding to be the passed in symbol table. The can only be done between top-level values. As symbols are written this symbol table is used to resolve them. If the symbols are undefined this symbol table is updated to include them as local symbols. The updated symbol table will be written before any of the local values are emitted.

If the symbol table is the system symbol table an Ion version marker will be written to the output. If symbols not in the system symbol table are written a local symbol table will be created and written before the current top level value.

Specified by:

setSymbolTable in class _Private_IonWriterBase

Parameters:

symbols - base symbol table for encoding. Must not be null.

Throws:

java.io.IOException

getSymbolTable

public final SymbolTable getSymbolTable()

Description copied from interface: IonWriter

Gets the symbol table that is currently in use by the writer. While writing a number of values the symbol table will be populated with any added symbols.

Note that the table may be replaced during processing. For example, the stream may start out with a system table that's later replaced by a local table in order to store newly-encountered symbols.

When this method returns a local table, it may be mutable, meaning that additional symbols may be interned until it is made read-only. Note that manually mutating local symbol tables is a deprecated feature; please instead use IonSystem.newBinaryWriter(java.io.OutputStream, SymbolTable...) or IonSystem.newTextWriter(java.io.OutputStream, SymbolTable...) to provide custom symbol table(s) to writers upon construction.

Specified by:

getSymbolTable in interface IonWriter

Returns:

current symbol table

setFieldName

public final void setFieldName(java.lang.String name)

Description copied from interface: IonWriter

Sets the pending field name to the given text.

The pending field name is cleared when the current value is written via stepIn() or one of the write*() methods.

Specified by:

setFieldName in interface IonWriter

Parameters:

name - text of the field name

setFieldNameSymbol

public final void setFieldNameSymbol(SymbolToken name)

Description copied from interface: IonWriter

Sets the pending field name to the given token.

The pending field name is cleared when the current value is written via stepIn() or one of the write*() methods.

Specified by:

setFieldNameSymbol in interface IonWriter

Parameters:

name - text of the field name

isFieldNameSet

public final boolean isFieldNameSet()

Description copied from class: _Private_IonWriterBase

Returns true if the field name has been set either through setFieldName or setFieldId. This is generally more efficient than calling getFieldName or getFieldId and checking the return type as it does not need to resolve the name through a symbol table. This returns false if the field name has not been set.

Specified by:

isFieldNameSet in interface _Private_IonWriter

Specified by:

isFieldNameSet in class _Private_IonWriterBase

Returns:

true if a field name has been set false otherwise

addTypeAnnotation

public void addTypeAnnotation(java.lang.String annotation)

Description copied from interface: IonWriter

Adds a given string to the list of pending annotations.

The list of pending annotations is cleared when the current value is written via stepIn() or one of the write*() methods.

Specified by:

addTypeAnnotation in interface IonWriter

Parameters:

annotation - string annotation to append to the annotation list

setTypeAnnotations

public void setTypeAnnotations(java.lang.String... annotations)

Description copied from interface: IonWriter

Sets the full list of pending annotations to the given text symbols. Any pending annotations are cleared. The contents of the annotations array are copied into this writer, so the caller does not need to preserve the array.

The list of pending annotations is cleared when the current value is written via stepIn() or one of the write*() methods.

Specified by:

setTypeAnnotations in interface IonWriter

Parameters:

annotations - string array with the annotations. If null or empty, any pending annotations are cleared.

setTypeAnnotationSymbols

public void setTypeAnnotationSymbols(SymbolToken... annotations)

Description copied from interface: IonWriter

Sets the full list of pending annotations to the given symbols. Any pending annotations are cleared. The contents of the annotations array are copied into this writer, so the caller does not need to preserve the array.

The list of pending annotations is cleared when the current value is written via stepIn() or one of the write*() methods.

This is an "expert method": correct use requires deep understanding of the Ion binary format. You almost certainly don't want to use it.

Specified by:

setTypeAnnotationSymbols in interface IonWriter

Parameters:

annotations - If null or empty, any pending annotations are cleared.

stepIn

public void stepIn(IonType containerType)
            throws java.io.IOException

Description copied from interface: IonWriter

Writes the beginning of a non-null container (list, sexp, or struct). This must be matched by a call to IonWriter.stepOut() after the last child value.

This method is not used to write null.list et al. To write null values use IonWriter.writeNull(IonType).

Specified by:

stepIn in interface IonWriter

Parameters:

containerType - must be one of IonType.LIST, IonType.SEXP, or IonType.STRUCT.

Throws:

java.io.IOException

stepOut

public void stepOut()
             throws java.io.IOException

Description copied from interface: IonWriter

Writes the end of the current container, returning this writer to the context of parent container. Invocation of this method must match a preceding call to IonWriter.stepIn(IonType).

Specified by:

stepOut in interface IonWriter

Throws:

java.io.IOException

writeBlob

public void writeBlob(byte[] value,
                      int start,
                      int len)
               throws java.io.IOException

Description copied from interface: IonWriter

Writes a portion of the byte array out as an IonBlob value. This copies the portion of the byte array that is written.

Specified by:

writeBlob in interface IonWriter

Parameters:

value - bytes to be written. May be null to represent null.blob.

start - offset of the first byte in value to write

len - number of bytes to write from value

Throws:

java.io.IOException

writeBool

public void writeBool(boolean value)
               throws java.io.IOException

Description copied from interface: IonWriter

writes a non-null boolean value (true or false) as an IonBool to output.

Specified by:

writeBool in interface IonWriter

Parameters:

value - true or false as desired

Throws:

java.io.IOException

writeClob

public void writeClob(byte[] value,
                      int start,
                      int len)
               throws java.io.IOException

Description copied from interface: IonWriter

Writes a portion of the byte array out as an IonClob value. This copies the porition of the byte array that is written.

Specified by:

writeClob in interface IonWriter

Parameters:

value - bytes to be written. May be null to represent null.clob.

start - offset of the first byte in value to write

len - number of bytes to write from value

Throws:

java.io.IOException

writeDecimal

public void writeDecimal(java.math.BigDecimal value)
                  throws java.io.IOException

Description copied from interface: IonWriter

Writes a BigDecimal value as an Ion decimal. Ion uses an arbitrarily long sign/value and an arbitrarily long signed exponent to write the value. This preserves all of the BigDecimal digits, the number of significant digits.

To write a negative zero value, pass this method a Decimal instance.

Specified by:

writeDecimal in interface IonWriter

Specified by:

writeDecimal in class _Private_IonWriterBase

Parameters:

value - may be null to represent null.decimal.

Throws:

java.io.IOException

writeFloat

public void writeFloat(double value)
                throws java.io.IOException

Description copied from interface: IonWriter

writes a 64 bit binary floating point value, a Java double, as an IonFloat. Currently IonFloat values are output as 64 bit IEEE 754 big endian values. IonFloat preserves all valid floating point values, including -0.0, Nan and +/-infinity. It does not guarantee preservation of -Nan or other less less "common" values.

Specified by:

writeFloat in interface IonWriter

Parameters:

value - double to write

Throws:

java.io.IOException

writeInt

public void writeInt(int value)
              throws java.io.IOException

Throws:

java.io.IOException

writeInt

public void writeInt(long value)
              throws java.io.IOException

Description copied from interface: IonWriter

writes a signed 64 bit value, a Java long, as an IonInt.

Specified by:

writeInt in interface IonWriter

Parameters:

value - signed int to write

Throws:

java.io.IOException

writeInt

public void writeInt(java.math.BigInteger value)
              throws java.io.IOException

Description copied from interface: IonWriter

writes a BigInteger value as an IonInt. If the BigInteger value is null this writes a null int.

Specified by:

writeInt in interface IonWriter

Parameters:

value - BigInteger to write

Throws:

java.io.IOException

writeNull

public void writeNull(IonType type)
               throws java.io.IOException

Description copied from interface: IonWriter

Writes a null value of a specified Ion type.

Specified by:

writeNull in interface IonWriter

Parameters:

type - type of the null to be written

Throws:

java.io.IOException

writeString

public void writeString(java.lang.String value)
                 throws java.io.IOException

Description copied from interface: IonWriter

Writes a String as an Ion string. Since Ion strings are UTF-8 and Java Strings are Unicode 16. As such the resulting lengths may not match. In addition some Java strings are not valid as they may contain only one of the two needed surrogate code units necessary to define the Unicode code point to be output, an exception will be raised if this case is encountered.

Specified by:

writeString in interface IonWriter

Parameters:

value - may be null to represent null.string.

Throws:

java.io.IOException

writeSymbol

public final void writeSymbol(java.lang.String value)
                       throws java.io.IOException

Description copied from interface: IonWriter

Writes the text of an Ion symbol value.

Specified by:

writeSymbol in interface IonWriter

Parameters:

value - may be null to represent null.symbol.

Throws:

java.io.IOException

writeIonVersionMarker

public final void writeIonVersionMarker()
                                 throws java.io.IOException

Description copied from interface: _Private_IonWriter

Write an Ion version marker symbol to the output. This is the $ion_1_0 value currently (in later versions the number may change). In text output this appears as the text symbol. In binary this will be the symbol id if the writer is in a list, sexp or struct. If the writer is currently at the top level this will write the "magic cookie" value. Writing a version marker will reset the symbol table to be the system symbol table.

Specified by:

writeIonVersionMarker in interface _Private_IonWriter

Throws:

java.io.IOException

writeTimestamp

public void writeTimestamp(Timestamp value)
                    throws java.io.IOException

Description copied from interface: IonWriter

Writes a timestamp value.

Specified by:

writeTimestamp in interface IonWriter

Parameters:

value - may be null to represent null.timestamp.

Throws:

java.io.IOException