Package com.amazon.ion

Interface IonWriter

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable, Faceted, java.io.Flushable
    All Known Subinterfaces:
    _Private_IonManagedWriter, _Private_IonRawWriter, _Private_IonWriter, _Private_ListWriter, IonBinaryWriter
    All Known Implementing Classes:
    _Private_IonBinaryWriterImpl, _Private_IonWriterBase
    public interface IonWriter
extends java.io.Closeable, java.io.Flushable, Faceted
    Writes Ion data to an output source. This interface allows the user to write Ion data without being concerned about which output format is being used.

    WARNING: This interface should not be implemented or extended by code outside of this library.

    A value is written via the set of typed write*() methods such as writeBool(boolean) and writeInt(long). Each of these methods outputs a single Ion value, and afterwards the writer is prepared to receive the data for the next sibling value.

    Any type annotations must be set before the value is written. Once the value has been written the "pending annotations" are erased, so they are must be set again if they need to be applied to the next value.

    Similarly the field name must be set before the value is written (assuming the value is a field in a structure). The field name is also "erased" once used, so it must be set for each field.

    To write a container, first write any annotations and/or field name applicable to the container itself. Then call stepIn(IonType) with the desired container type. Then write each child value in order. Finally, call stepOut() to complete the container.

    Once all the top-level values have been written (and stepped-out back to the starting level), the caller must close() the writer (or at least flush() or finish() it) before accessing the data written to the underlying data sink (for example, via ByteArrayOutputStream.toByteArray()). The writer may have internal buffers and without closing, flushing, or finishing it, it may not have written everything to the underlying data sink.

    Exception Handling

    IonWriter is a generic interface for generating Ion data, and it's not possible to fully specify the set of exceptions that could be thrown from the underlying data sink. Thus all failures are thrown as instances of IonException, wrapping the originating cause. If an application wants to handle (say) IOExceptions specially, then it needs to extract that from the wrappers; the documentation of IonException explains how to do that.
    See Also:
    IonStreamUtils, IonTextWriterBuilder

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      void addTypeAnnotation​(java.lang.String annotation)
      Adds a given string to the list of pending annotations.
      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.
      SymbolTable getSymbolTable()
      Gets the symbol table that is currently in use by the writer.
      boolean isInStruct()
      Determines whether values are being written as fields of a struct.
      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 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)
      write the byte array out as an IonBlob value.
      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 writeClob​(byte[] value)
      write the byte array out as an IonClob value.
      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 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 writeNull()
      Writes a value of Ion's null type (null aka null.null).
      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 writeSymbol​(java.lang.String content)
      Writes the text of an Ion symbol value.
      void writeSymbolToken​(SymbolToken content)
      Writes the content of an Ion symbol value.
      void writeTimestamp​(Timestamp value)
      Writes a timestamp value.
      void writeTimestampUTC​(java.util.Date value)
      Deprecated.
      Use IonWriter.writeTimestamp(Timestamp.forDateZ(Date)) instead.
      void writeValue​(IonReader reader)
      Writes the current value from a reader.
      void writeValue​(IonValue value)
      Deprecated.
      Use IonValue.writeTo(IonWriter) instead.
      void writeValues​(IonReader reader)
      Writes a reader's current value, and all following values until the end of the current container.

    • Method Detail

      • getSymbolTable

        SymbolTable getSymbolTable()
        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.

        Returns:
        current symbol table

      • flush

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

      • finish

        void finish()
     throws java.io.IOException
        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 flush() instead to avoid re-declaring the local symbol table unnecessarily.

        Throws:
        java.io.IOException - if thrown by the underlying output target.
        java.lang.IllegalStateException - when not between top-level values.
        See Also:
        flush(), close()

      • close

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

      • setFieldName

        void setFieldName​(java.lang.String name)
        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.

        Parameters:
        name - text of the field name
        Throws:
        java.lang.IllegalStateException - if the current container isn't a struct, that is, if isInStruct() is false.
        java.lang.NullPointerException - if name is null.

      • setFieldNameSymbol

        void setFieldNameSymbol​(SymbolToken name)
        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.

        Parameters:
        name - text of the field name
        Throws:
        java.lang.IllegalStateException - if the current container isn't a struct, that is, if isInStruct() is false.
        java.lang.NullPointerException - if name is null.

      • setTypeAnnotations

        void setTypeAnnotations​(java.lang.String... annotations)
        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.

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

      • setTypeAnnotationSymbols

        void setTypeAnnotationSymbols​(SymbolToken... annotations)
        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.

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

      • addTypeAnnotation

        void addTypeAnnotation​(java.lang.String annotation)
        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.

        Parameters:
        annotation - string annotation to append to the annotation list

      • stepIn

        void stepIn​(IonType containerType)
     throws java.io.IOException
        Writes the beginning of a non-null container (list, sexp, or struct). This must be matched by a call to stepOut() after the last child value.

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

        Parameters:
        containerType - must be one of IonType.LIST, IonType.SEXP, or IonType.STRUCT.
        Throws:
        java.io.IOException

      • stepOut

        void stepOut()
      throws java.io.IOException
        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 stepIn(IonType).
        Throws:
        java.io.IOException

      • isInStruct

        boolean isInStruct()
        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.
        Returns:
        true when the parent is a struct.

      • writeValue

        @Deprecated
void writeValue​(IonValue value)
         throws java.io.IOException
        Deprecated.
        Use IonValue.writeTo(IonWriter) instead.
        writes the contents of the passed in Ion value to the output.

        This method also writes annotations and field names (if in a struct), and performs a deep write, including the contents of any containers encountered.

        Parameters:
        value - may be null, in which case this method does nothing.
        Throws:
        java.io.IOException

      • writeValue

        void writeValue​(IonReader reader)
         throws java.io.IOException
        Writes the current value from a reader.

        This method also writes annotations and field names (if in a struct), and performs a deep write, including the contents of any containers encountered.

        Throws:
        java.io.IOException

      • writeValues

        void writeValues​(IonReader reader)
          throws java.io.IOException
        Writes a reader's current value, and all following values until the end of the current container. If there's no current value then this method calls IonReader.next() to get going.

        This method iterates until IonReader.next() returns null and does not step out to the container of the current cursor position.

        This method also writes annotations and field names (if in a struct), and performs a deep write, including the contents of any containers encountered.

        Throws:
        java.io.IOException

      • writeNull

        void writeNull()
        throws java.io.IOException
        Writes a value of Ion's null type (null aka null.null).
        Throws:
        java.io.IOException

      • writeNull

        void writeNull​(IonType type)
        throws java.io.IOException
        Writes a null value of a specified Ion type.
        Parameters:
        type - type of the null to be written
        Throws:
        java.io.IOException

      • writeBool

        void writeBool​(boolean value)
        throws java.io.IOException
        writes a non-null boolean value (true or false) as an IonBool to output.
        Parameters:
        value - true or false as desired
        Throws:
        java.io.IOException

      • writeInt

        void writeInt​(long value)
       throws java.io.IOException
        writes a signed 64 bit value, a Java long, as an IonInt.
        Parameters:
        value - signed int to write
        Throws:
        java.io.IOException

      • writeInt

        void writeInt​(java.math.BigInteger value)
       throws java.io.IOException
        writes a BigInteger value as an IonInt. If the BigInteger value is null this writes a null int.
        Parameters:
        value - BigInteger to write
        Throws:
        java.io.IOException

      • writeFloat

        void writeFloat​(double value)
         throws java.io.IOException
        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.
        Parameters:
        value - double to write
        Throws:
        java.io.IOException

      • writeDecimal

        void writeDecimal​(java.math.BigDecimal value)
           throws java.io.IOException
        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.

        Parameters:
        value - may be null to represent null.decimal.
        Throws:
        java.io.IOException

      • writeTimestamp

        void writeTimestamp​(Timestamp value)
             throws java.io.IOException
        Writes a timestamp value.
        Parameters:
        value - may be null to represent null.timestamp.
        Throws:
        java.io.IOException

      • writeTimestampUTC

        @Deprecated
void writeTimestampUTC​(java.util.Date value)
                throws java.io.IOException
        Deprecated.
        Use IonWriter.writeTimestamp(Timestamp.forDateZ(Date)) instead.
        writes the passed in Date (in milliseconds since the epoch) as an IonTimestamp. The Date value is treated as a UTC value with an unknown timezone offset (a z value).
        Parameters:
        value - java.util Date holding the UTC timestamp; may be null to represent null.timestamp.
        Throws:
        java.io.IOException

      • writeSymbol

        void writeSymbol​(java.lang.String content)
          throws java.io.IOException
        Writes the text of an Ion symbol value.
        Parameters:
        content - may be null to represent null.symbol.
        Throws:
        java.lang.IllegalArgumentException - if the value contains an invalid UTF-16 surrogate pair.
        java.io.IOException

      • writeSymbolToken

        void writeSymbolToken​(SymbolToken content)
               throws java.io.IOException
        Writes the content of an Ion symbol value.
        Parameters:
        content - may be null to represent null.symbol.
        Throws:
        java.lang.IllegalArgumentException - if the value contains an invalid UTF-16 surrogate pair.
        java.io.IOException

      • writeString

        void writeString​(java.lang.String value)
          throws java.io.IOException
        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.
        Parameters:
        value - may be null to represent null.string.
        Throws:
        java.lang.IllegalArgumentException - if the value contains an invalid UTF-16 surrogate pair.
        java.io.IOException

      • writeClob

        void writeClob​(byte[] value)
        throws java.io.IOException
        write the byte array out as an IonClob value. This copies the byte array.
        Parameters:
        value - may be null to represent null.clob.
        Throws:
        java.io.IOException

      • writeClob

        void writeClob​(byte[] value,
               int start,
               int len)
        throws java.io.IOException
        Writes a portion of the byte array out as an IonClob value. This copies the porition of the byte array that is written.
        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

      • writeBlob

        void writeBlob​(byte[] value)
        throws java.io.IOException
        write the byte array out as an IonBlob value. This copies the byte array.
        Parameters:
        value - may be null to represent null.blob.
        Throws:
        java.io.IOException

      • writeBlob

        void writeBlob​(byte[] value,
               int start,
               int len)
        throws java.io.IOException
        Writes a portion of the byte array out as an IonBlob value. This copies the portion of the byte array that is written.
        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