This writer handles the symbol table processing and provides default implementations for the list forms of the write methods as often the list form is not susceptible to optimization.
This writer has a (_system_writer) to which the actual data is
written, but data flows through the _current_writer most of the
time.
The critical responsibility here is the recognition of IVMs and local symbol
tables. When the user starts writing a local symtab, the stream is diverted
away from the _system_writer into a temporary tree writer that
collects the symtab data into an IonStruct instance. When that
struct is stepped-out, the diversion is stopped and the new
SymbolTable is installed.
| Modifier and Type | Field and Description |
|---|---|
| private final IonCatalog | _catalog
Used to make correct local symbol tables. |
| pack-priv IonWriterSystem | _current_writer
This will be either our |
| private IonStruct | _symbol_table_value
While the stream is diverted to collect local symtab data, it is being written to this instance. |
| private final ValueFactory | _symtab_value_factory
Factory for constructing the DOM of local symtabs. |
| pack-priv final IonWriterSystem | _system_writer
The underlying system writer that writing the raw format (text, binary, or ion values). |
| Access | Constructor and Description |
|---|---|
| pack-priv | IonWriterUser(IonCatalog
may be null. catalog, ValueFactory must not be null. symtabValueFactory, IonWriterSystem must not be null. systemWriter, boolean requireSymbolValidation)Base constructor. |
| pack-priv | IonWriterUser(IonCatalog
may be null catalog, ValueFactory must not be null symtabValueFactory, IonWriterSystem must not be null systemWriter, SymbolTable must not be null symtab, boolean requireSymbolValidation)Constructor for text and binary writers. |
| Modifier and Type | Method and Description |
|---|---|
| pack-priv SymbolTable | |
| public void | addTypeAnnotation(String
string annotation to append to the annotation list annotation)Implements com. Adds a given string to the list of pending annotations. |
| pack-priv final String | assumeKnownSymbol(int sid)
Implements abstract com. Translates a symbol using the current symtab. |
| public void | close()
Implements com. Closes this stream and releases any system resources associated with it. |
| private void | close_local_symbol_table_copy()
Closes the diverted writer since the local symbol table
is complete (i.e. the struct is closed, on |
| pack-priv int | findAnnotation(String
the annotation to find. name)Implements abstract com. Returns the given annotation's index in the value's annotations list, or -1 if not present. |
| public final void | finish()
Implements com. 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. |
| public void | flush()
Implements com. Flushes this writer by writing any buffered output to the underlying output target without finalizing the stream's local symbol table. |
| public IonCatalog | getCatalog()
Implements com. Mostly for testing at this point, but could be useful public API. |
| public int | getDepth()
Implements abstract com. Implements com. Returns the current depth of containers the writer is at. |
| public final SymbolTable | getSymbolTable()
Implements com. Gets the symbol table that is currently in use by the writer. |
| pack-priv int[] | getTypeAnnotationIds()
Implements abstract com. Gets the current list of pending annotations. |
| pack-priv String[] | getTypeAnnotations()
Implements abstract com. Gets the current list of pending annotations. |
| pack-priv final SymbolToken[] | |
| public final boolean | isFieldNameSet()
Implements abstract com. Implements com. Returns true if the field name has been set either through setFieldName or setFieldId. |
| public boolean | isInStruct()
Implements com. Determines whether values are being written as fields of a struct. |
| private void | open_local_symbol_table_copy()
Diverts the data stream to a temporary tree writer which collects
local symtab data into an IonStruct from which we'll later construct a
|
| public final void | setFieldName(String
text of the field name name)Implements com. Sets the pending field name to the given text. |
| public final void | setFieldNameSymbol(SymbolToken
text of the field name name)Implements com. Sets the pending field name to the given token. |
| public final void | setSymbolTable(SymbolTable
base symbol table for encoding. Must not be null. symbols)Implements abstract com. Sets the symbol table to use for encoding to be the passed in symbol table. |
| public void | setTypeAnnotations(String...
string array with the annotations.
If null or empty, any pending annotations are cleared. annotations)Implements com. Sets the full list of pending annotations to the given text symbols. |
| public void | setTypeAnnotationSymbols(SymbolToken...
If null or empty, any pending annotations are cleared. annotations)Implements com. Sets the full list of pending annotations to the given symbols. |
| public void | stepIn(IonType containerType)
Implements com. Writes the beginning of a non-null container (list, sexp, or struct). |
| public void | stepOut()
Implements com. Writes the end of the current container, returning this writer to the context of parent container. |
| private boolean | |
| public void | writeBlob(byte[]
bytes to be written.
May be value, int null to represent null.blob.offset of the first byte in value to write start, int number of bytes to write from value len)Implements com. Writes a portion of the byte array out as an IonBlob value. |
| public void | writeBool(boolean
true or false as desired value)Implements com. writes a non-null boolean value (true or false) as an IonBool to output. |
| public void | writeClob(byte[]
bytes to be written.
May be value, int null to represent null.clob.offset of the first byte in value to write start, int number of bytes to write from value len)Implements com. Writes a portion of the byte array out as an IonClob value. |
| public void | writeDecimal(BigDecimal
may be null to represent value)null.decimal.Implements abstract com. Implements com. Writes a BigDecimal value as an Ion decimal. |
| public void | writeFloat(double
double to write value)Implements com. writes a 64 bit binary floating point value, a Java double, as an IonFloat. |
| public void | |
| public void | writeInt(long
signed int to write value)Implements com. writes a signed 64 bit value, a Java long, as an IonInt. |
| public void | writeInt(BigInteger
BigInteger to write value)Implements com. writes a BigInteger value as an IonInt. |
| pack-priv final void | |
| public final void | writeIonVersionMarker()
Implements abstract com. Implements com. Write an Ion version marker symbol to the output. |
| public void | writeNull(IonType
type of the null to be written type)Implements com. Writes a null value of a specified Ion type. |
| public void | writeString(String
may be null to represent value)null.string.Implements com. Writes a |
| pack-priv final void | writeSymbol(int
symbol table id to write symbolId)Implements abstract com. Write symbolId out as an IonSymbol value. |
| public final void | writeSymbol(String
may be null to represent value)null.symbol.Implements com. Writes the text of an Ion symbol value. |
| public void | writeTimestamp(Timestamp
may be null to represent value)null.timestamp.Implements com. Writes a timestamp value. |
| _catalog | back to summary |
|---|---|
| private final IonCatalog _catalog Used to make correct local symbol tables. May be null. | |
| _current_writer | back to summary |
|---|---|
| pack-priv IonWriterSystem _current_writer This will be either our | |
| _symbol_table_value | back to summary |
|---|---|
| private IonStruct _symbol_table_value While the stream is diverted to collect local symtab data, it is
being written to this instance.
This is null IFF | |
| _symtab_value_factory | back to summary |
|---|---|
| private final ValueFactory _symtab_value_factory Factory for constructing the DOM of local symtabs. Not null. | |
| _system_writer | back to summary |
|---|---|
| pack-priv final IonWriterSystem _system_writer The underlying system writer that writing the raw format (text, binary, or ion values). Not null. | |
| IonWriterUser | back to summary |
|---|---|
| pack-priv IonWriterUser(IonCatalog catalog, ValueFactory symtabValueFactory, IonWriterSystem systemWriter, boolean requireSymbolValidation) Base constructor.
POSTCONDITION:
| |
| IonWriterUser | back to summary |
|---|---|
| pack-priv IonWriterUser(IonCatalog catalog, ValueFactory symtabValueFactory, IonWriterSystem systemWriter, SymbolTable symtab, boolean requireSymbolValidation) Constructor for text and binary writers.
POSTCONDITION:
| |
| activeSystemSymbolTable | back to summary |
|---|---|
| pack-priv SymbolTable activeSystemSymbolTable() | |
| addTypeAnnotation | back to summary |
|---|---|
| public void addTypeAnnotation(String annotation) Implements com. Doc from com. Adds a given string to the list of pending annotations.
The list of pending annotations is cleared when the current value is
written via
| |
| assumeKnownSymbol | back to summary |
|---|---|
| pack-priv final String assumeKnownSymbol(int sid) Implements abstract com. Doc from com. Translates a symbol using the current symtab. | |
| close | back to summary |
|---|---|
| public void close() throws IOException Implements com. Doc from com. 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
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_local_symbol_table_copy | back to summary |
|---|---|
| private void close_local_symbol_table_copy() throws IOException Closes the diverted writer since the local symbol table
is complete (i.e. the struct is closed, on | |
| findAnnotation | back to summary |
|---|---|
| pack-priv int findAnnotation(String name) Implements abstract com. Doc from com. Returns the given annotation's index in the value's annotations list, or -1 if not present. | |
| finish | back to summary |
|---|---|
| public final void finish() throws IOException Implements com. Doc from com. 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
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
| |
| flush | back to summary |
|---|---|
| public void flush() throws IOException Implements com. Doc from com. 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
| |
| getCatalog | back to summary |
|---|---|
| public IonCatalog getCatalog() Implements com. Doc from com. Mostly for testing at this point, but could be useful public API. | |
| getDepth | back to summary |
|---|---|
| public int getDepth() Implements abstract com. Implements com. Doc from com. Returns the current depth of containers the writer is at. This is 0 if the writer is at top-level.
| |
| getSymbolTable | back to summary |
|---|---|
| public final SymbolTable getSymbolTable() Implements com. Doc from com. 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
| |
| getTypeAnnotationIds | back to summary |
|---|---|
| pack-priv int[] getTypeAnnotationIds() Implements abstract com. Doc from com. Gets the current list of pending annotations.
This is the contents of the current If the annotations were set as string they will be converted to symbol IDs (ints) if a symbol table is available. In the event a symbol table is not available a null array will be returned. If no annotations are set a 0 length array will be returned.
| |
| getTypeAnnotations | back to summary |
|---|---|
| pack-priv String[] getTypeAnnotations() Implements abstract com. Doc from com. Gets the current list of pending annotations.
This is the contents of the current If the annotations were set as IDs they will be converted if a symbol table is available. In the event a symbol table is not available a null array will be returned. If no annotations are set a 0 length array will be returned.
| |
| getTypeAnnotationSymbols | back to summary |
|---|---|
| pack-priv final SymbolToken[] getTypeAnnotationSymbols() | |
| isFieldNameSet | back to summary |
|---|---|
| public final boolean isFieldNameSet() Implements abstract com. Implements com. Doc from com. 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.
| |
| isInStruct | back to summary |
|---|---|
| public boolean isInStruct() Implements com. Doc from com. 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.
| |
| open_local_symbol_table_copy | back to summary |
|---|---|
| private void open_local_symbol_table_copy()
Diverts the data stream to a temporary tree writer which collects
local symtab data into an IonStruct from which we'll later construct a
Once the value image of the symbol table is complete (which happens when the caller steps out of the containing struct) the diverted stream is abandonded and the symbol table gets constructed. If there was a makeSymbolTable(Reader) this copy might be, at least partially, avoided. | |
| setFieldName | back to summary |
|---|---|
| public final void setFieldName(String name) Implements com. Doc from com. Sets the pending field name to the given text.
The pending field name is cleared when the current value is
written via
| |
| setFieldNameSymbol | back to summary |
|---|---|
| public final void setFieldNameSymbol(SymbolToken name) Implements com. Doc from com. Sets the pending field name to the given token.
The pending field name is cleared when the current value is
written via
| |
| setSymbolTable | back to summary |
|---|---|
| public final void setSymbolTable(SymbolTable symbols) throws IOException Implements abstract com. Doc from com. 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.
| |
| setTypeAnnotations | back to summary |
|---|---|
| public void setTypeAnnotations(String... annotations) Implements com. Doc from com. Sets the full list of pending annotations to the given text symbols.
Any pending annotations are cleared.
The contents of the
The list of pending annotations is cleared when the current value is
written via
| |
| setTypeAnnotationSymbols | back to summary |
|---|---|
| public void setTypeAnnotationSymbols(SymbolToken... annotations) Implements com. Doc from com. Sets the full list of pending annotations to the given symbols.
Any pending annotations are cleared.
The contents of the
The list of pending annotations is cleared when the current value is
written via This is an "expert method": correct use requires deep understanding of the Ion binary format. You almost certainly don't want to use it.
| |
| stepIn | back to summary |
|---|---|
| public void stepIn(IonType containerType) throws IOException Implements com. Doc from com. Writes the beginning of a non-null container (list, sexp, or struct).
This must be matched by a call to
This method is not used to write
| |
| stepOut | back to summary |
|---|---|
| public void stepOut() throws IOException Implements com. Doc from com. 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
| |
| symbol_table_being_collected | back to summary |
|---|---|
| private boolean symbol_table_being_collected() | |
| writeBlob | back to summary |
|---|---|
| public void writeBlob(byte[] value, int start, int len) throws IOException Implements com. Doc from com. Writes a portion of the byte array out as an IonBlob value. This copies the portion of the byte array that is written.
| |
| writeBool | back to summary |
|---|---|
| public void writeBool(boolean value) throws IOException Implements com. Doc from com. writes a non-null boolean value (true or false) as an IonBool to output.
| |
| writeClob | back to summary |
|---|---|
| public void writeClob(byte[] value, int start, int len) throws IOException Implements com. Doc from com. Writes a portion of the byte array out as an IonClob value. This copies the porition of the byte array that is written.
| |
| writeDecimal | back to summary |
|---|---|
| public void writeDecimal(BigDecimal value) throws IOException Implements abstract com. Implements com. Doc from com. 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
| |
| writeFloat | back to summary |
|---|---|
| public void writeFloat(double value) throws IOException Implements com. Doc from com. 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.
| |
| writeInt | back to summary |
|---|---|
public void writeInt(int value) throws IOException
| |
| writeInt | back to summary |
|---|---|
| public void writeInt(long value) throws IOException Implements com. Doc from com. writes a signed 64 bit value, a Java long, as an IonInt.
| |
| writeInt | back to summary |
|---|---|
| public void writeInt(BigInteger value) throws IOException Implements com. Doc from com. writes a BigInteger value as an IonInt. If the BigInteger value is null this writes a null int.
| |
| writeIonVersionMarker | back to summary |
|---|---|
| pack-priv final void writeIonVersionMarker(SymbolTable systemSymtab) throws IOException | |
| writeIonVersionMarker | back to summary |
|---|---|
| public final void writeIonVersionMarker() throws IOException Implements abstract com. Implements com. Doc from com. 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.
| |
| writeNull | back to summary |
|---|---|
| public void writeNull(IonType type) throws IOException Implements com. Doc from com. Writes a null value of a specified Ion type.
| |
| writeString | back to summary |
|---|---|
| public void writeString(String value) throws IOException Implements com. Doc from com. Writes a
| |
| writeSymbol | back to summary |
|---|---|
| pack-priv final void writeSymbol(int symbolId) throws IOException Implements abstract com. Doc from com. Write symbolId out as an IonSymbol value. The value must be valid in the symbol table.
| |
| writeSymbol | back to summary |
|---|---|
| public final void writeSymbol(String value) throws IOException Implements com. Doc from com. Writes the text of an Ion symbol value.
| |
| writeTimestamp | back to summary |
|---|---|
| public void writeTimestamp(Timestamp value) throws IOException Implements com. Doc from com. Writes a timestamp value.
| |