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, Closeable, Flushable, 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.

  • Method Details

    • 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 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:
      IOException

    • getBytes

      public int getBytes(byte[] bytes, int offset, int len) throws 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:
      IOException

    • writeBytes

      public int writeBytes(OutputStream userstream) throws 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:
      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 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:
      IOException

    • writeBoolList

      public void writeBoolList(boolean[] values) throws IOException
      Specified by:
      writeBoolList in interface _Private_ListWriter
      Throws:
      IOException

    • writeFloatList

      public void writeFloatList(float[] values) throws IOException
      Specified by:
      writeFloatList in interface _Private_ListWriter
      Throws:
      IOException

    • writeFloatList

      public void writeFloatList(double[] values) throws IOException
      Specified by:
      writeFloatList in interface _Private_ListWriter
      Throws:
      IOException

    • writeIntList

      public void writeIntList(byte[] values) throws IOException
      Specified by:
      writeIntList in interface _Private_ListWriter
      Throws:
      IOException

    • writeIntList

      public void writeIntList(short[] values) throws IOException
      Specified by:
      writeIntList in interface _Private_ListWriter
      Throws:
      IOException

    • writeIntList

      public void writeIntList(int[] values) throws IOException
      Specified by:
      writeIntList in interface _Private_ListWriter
      Throws:
      IOException

    • writeIntList

      public void writeIntList(long[] values) throws IOException
      Specified by:
      writeIntList in interface _Private_ListWriter
      Throws:
      IOException

    • writeStringList

      public void writeStringList(String[] values) throws IOException
      Specified by:
      writeStringList in interface _Private_ListWriter
      Throws:
      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 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 Flushable
      Specified by:
      flush in interface IonWriter
      Throws:
      IOException - if thrown by the underlying output target.
      See Also:

    • close

      public void close() throws 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 AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface IonWriter
      Throws:
      IOException - if thrown by the underlying output target.
      See Also:

    • finish

      public final void finish() throws 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:
      IOException - if thrown by the underlying output target.
      See Also:

    • setSymbolTable

      public final void setSymbolTable(SymbolTable symbols) throws 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:
      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(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(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(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 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:
      IOException

    • stepOut

      public void stepOut() throws 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:
      IOException

    • writeBlob

      public void writeBlob(byte[] value, int start, int len) throws 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:
      IOException

    • writeBool

      public void writeBool(boolean value) throws 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:
      IOException

    • writeClob

      public void writeClob(byte[] value, int start, int len) throws 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:
      IOException

    • writeDecimal

      public void writeDecimal(BigDecimal value) throws 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:
      IOException

    • writeFloat

      public void writeFloat(double value) throws 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:
      IOException

    • writeInt

      public void writeInt(int value) throws IOException
      Throws:
      IOException

    • writeInt

      public void writeInt(long value) throws 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:
      IOException

    • writeInt

      public void writeInt(BigInteger value) throws 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:
      IOException

    • writeNull

      public void writeNull(IonType type) throws 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:
      IOException

    • writeString

      public void writeString(String value) throws 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:
      IOException

    • writeSymbol

      public final void writeSymbol(String value) throws 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:
      IOException

    • writeIonVersionMarker

      public final void writeIonVersionMarker() throws 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:
      IOException

    • writeTimestamp

      public void writeTimestamp(Timestamp value) throws 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:
      IOException