@Deprecated public final class _Private_IonBinaryWriterImpl extends _Private_IonWriterBase implements IonBinaryWriter
Adapts the binary IonWriter
implementation to the deprecated
IonBinaryWriter
interface.
ERROR_MISSING_FIELD_NAME
Modifier and Type | Method and 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(java.math.BigInteger value)
writes a BigInteger value as an IonInt.
|
void |
writeInt(int value) |
void |
writeInt(long value)
writes a signed 64 bit value, a Java long, 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.
|
asFacet, pop_passed_symbol_table, writeBlob, writeClob, writeFloat, writeNull, writeSymbolToken, writeTimestampUTC, writeValue, writeValues
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
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
public int byteSize()
IonBinaryWriter
IonBinaryWriter.getBytes()
or
IonBinaryWriter.getBytes(byte[], int, int)
.byteSize
in interface IonBinaryWriter
public byte[] getBytes() throws java.io.IOException
IonBinaryWriter
getBytes
in interface IonBinaryWriter
java.io.IOException
public int getBytes(byte[] bytes, int offset, int len) throws java.io.IOException
IonBinaryWriter
getBytes
in interface IonBinaryWriter
bytes
- users byte array to write intooffset
- initial offset in the array to write intolen
- maximum number of bytes to writejava.io.IOException
public int writeBytes(java.io.OutputStream userstream) throws java.io.IOException
IonBinaryWriter
writeBytes
in interface IonBinaryWriter
userstream
- OutputStream to write the bytes tojava.io.IOException
public boolean isStreamCopyOptimized()
_Private_IonWriter
IonWriter.writeValue(com.amazon.ion.IonReader)
.isStreamCopyOptimized
in interface _Private_IonWriter
isStreamCopyOptimized
in class _Private_IonWriterBase
public void writeValue(IonReader reader) throws java.io.IOException
_Private_IonWriterBase
writeValue
in interface IonWriter
writeValue
in class _Private_IonWriterBase
java.io.IOException
public void writeBoolList(boolean[] values) throws java.io.IOException
writeBoolList
in interface _Private_ListWriter
java.io.IOException
public void writeFloatList(float[] values) throws java.io.IOException
writeFloatList
in interface _Private_ListWriter
java.io.IOException
public void writeFloatList(double[] values) throws java.io.IOException
writeFloatList
in interface _Private_ListWriter
java.io.IOException
public void writeIntList(byte[] values) throws java.io.IOException
writeIntList
in interface _Private_ListWriter
java.io.IOException
public void writeIntList(short[] values) throws java.io.IOException
writeIntList
in interface _Private_ListWriter
java.io.IOException
public void writeIntList(int[] values) throws java.io.IOException
writeIntList
in interface _Private_ListWriter
java.io.IOException
public void writeIntList(long[] values) throws java.io.IOException
writeIntList
in interface _Private_ListWriter
java.io.IOException
public void writeStringList(java.lang.String[] values) throws java.io.IOException
writeStringList
in interface _Private_ListWriter
java.io.IOException
public IonCatalog getCatalog()
_Private_IonWriter
getCatalog
in interface _Private_IonWriter
public int getDepth()
_Private_IonWriterBase
getDepth
in interface _Private_IonWriter
getDepth
in class _Private_IonWriterBase
public boolean isInStruct()
IonWriter
isInStruct
in interface IonWriter
public void flush() throws java.io.IOException
IonWriter
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.
flush
in interface IonWriter
flush
in interface java.io.Flushable
java.io.IOException
- if thrown by the underlying output target.IonWriter.finish()
public void close() throws java.io.IOException
IonWriter
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.
close
in interface IonWriter
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
java.io.IOException
- if thrown by the underlying output target.IonWriter.finish()
public final void finish() throws java.io.IOException
IonWriter
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.
finish
in interface IonWriter
java.io.IOException
- if thrown by the underlying output target.IonWriter.flush()
,
IonWriter.close()
public final void setSymbolTable(SymbolTable symbols) throws java.io.IOException
_Private_IonWriterBase
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.
setSymbolTable
in class _Private_IonWriterBase
symbols
- base symbol table for encoding. Must not be null.java.io.IOException
public final SymbolTable getSymbolTable()
IonWriter
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.
getSymbolTable
in interface IonWriter
public final void setFieldName(java.lang.String name)
IonWriter
The pending field name is cleared when the current value is
written via stepIn()
or one of the
write*()
methods.
setFieldName
in interface IonWriter
name
- text of the field namepublic final void setFieldNameSymbol(SymbolToken name)
IonWriter
The pending field name is cleared when the current value is
written via stepIn()
or one of the
write*()
methods.
setFieldNameSymbol
in interface IonWriter
name
- text of the field namepublic final boolean isFieldNameSet()
_Private_IonWriterBase
isFieldNameSet
in interface _Private_IonWriter
isFieldNameSet
in class _Private_IonWriterBase
public void addTypeAnnotation(java.lang.String annotation)
IonWriter
The list of pending annotations is cleared when the current value is
written via stepIn()
or one of the
write*()
methods.
addTypeAnnotation
in interface IonWriter
annotation
- string annotation to append to the annotation listpublic void setTypeAnnotations(java.lang.String... annotations)
IonWriter
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.
setTypeAnnotations
in interface IonWriter
annotations
- string array with the annotations.
If null or empty, any pending annotations are cleared.public void setTypeAnnotationSymbols(SymbolToken... annotations)
IonWriter
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.
setTypeAnnotationSymbols
in interface IonWriter
annotations
- If null or empty, any pending annotations are cleared.public void stepIn(IonType containerType) throws java.io.IOException
IonWriter
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)
.
stepIn
in interface IonWriter
containerType
- must be one of
IonType.LIST
, IonType.SEXP
, or IonType.STRUCT
.java.io.IOException
public void stepOut() throws java.io.IOException
IonWriter
IonWriter.stepIn(IonType)
.public void writeBlob(byte[] value, int start, int len) throws java.io.IOException
IonWriter
public void writeBool(boolean value) throws java.io.IOException
IonWriter
public void writeClob(byte[] value, int start, int len) throws java.io.IOException
IonWriter
public void writeDecimal(java.math.BigDecimal value) throws java.io.IOException
IonWriter
To write a negative zero value, pass this method a
Decimal
instance.
writeDecimal
in interface IonWriter
writeDecimal
in class _Private_IonWriterBase
value
- may be null to represent null.decimal
.java.io.IOException
public void writeFloat(double value) throws java.io.IOException
IonWriter
writeFloat
in interface IonWriter
value
- double to writejava.io.IOException
public void writeInt(int value) throws java.io.IOException
java.io.IOException
public void writeInt(long value) throws java.io.IOException
IonWriter
public void writeInt(java.math.BigInteger value) throws java.io.IOException
IonWriter
public void writeNull(IonType type) throws java.io.IOException
IonWriter
public void writeString(java.lang.String value) throws java.io.IOException
IonWriter
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.writeString
in interface IonWriter
value
- may be null to represent null.string
.java.io.IOException
public final void writeSymbol(java.lang.String value) throws java.io.IOException
IonWriter
writeSymbol
in interface IonWriter
value
- may be null to represent null.symbol
.java.io.IOException
public final void writeIonVersionMarker() throws java.io.IOException
_Private_IonWriterBase
writeIonVersionMarker
in interface _Private_IonWriter
java.io.IOException
public void writeTimestamp(Timestamp value) throws java.io.IOException
IonWriter
writeTimestamp
in interface IonWriter
value
- may be null to represent null.timestamp
.java.io.IOException