diff --git a/src/main/java/com/amazon/ion/impl/IonWriter_1_1.kt b/src/main/java/com/amazon/ion/impl/IonWriter_1_1.kt new file mode 100644 index 0000000000..f85d526c7f --- /dev/null +++ b/src/main/java/com/amazon/ion/impl/IonWriter_1_1.kt @@ -0,0 +1,190 @@ +package com.amazon.ion.impl + +import com.amazon.ion.Decimal +import com.amazon.ion.IonType +import com.amazon.ion.Timestamp +import java.math.BigDecimal +import java.math.BigInteger +import java.time.Instant + +/** + * Writes Ion 1.1 data to an output source. + * + * This interface allows the user to write Ion data without being concerned about which output format is being used. + */ +interface IonWriter_1_1 { + + /** + * 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`)[stepOut]. + * + * Implementations should allow the application to continue writing further top-level values following the semantics + * for concatenating Ion data streams. + */ + fun finish() + + /** + * 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. + */ + fun close() + + /** Returns true if the writer is currently in a struct (indicating that field names are required). */ + fun isInStruct(): Boolean + + /** Returns the current depth of containers the writer is at. This is 0 if the writer is at top-level. */ + fun depth(): Int + + /** + * Writes the Ion 1.1 IVM. IVMs can only be written at the top level of an Ion stream. + * @throws com.amazon.ion.IonException if in any container. + */ + fun writeIVM() + + /** + * Writes one annotation for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: Int) + + /** + * Writes two annotations for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: Int, annotation1: Int) + + /** + * Writes three or more annotations for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: Int, annotation1: Int, vararg annotations: Int) + + /** + * Writes one annotation for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: CharSequence) + + /** + * Writes two annotations for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: CharSequence, annotation1: CharSequence) + + /** + * Writes three or more annotations for the next value. + * [writeAnnotations] may be called more than once to build up a list of annotations. + */ + fun writeAnnotations(annotation0: CharSequence, annotation1: CharSequence, vararg annotations: CharSequence) + + /** + * Writes the field name for the next value. Must be called while in a struct and must be called before [writeAnnotations]. + * @throws com.amazon.ion.IonException if annotations are already written for the value or if not in a struct. + */ + fun writeFieldName(text: CharSequence) + + /** + * Writes the field name for the next value. Must be called while in a struct and must be called before [writeAnnotations]. + * @throws com.amazon.ion.IonException if annotations are already written for the value or if not in a struct. + */ + fun writeFieldName(sid: Int) + + /** + * Steps into a List. + * + * The [delimited] parameter is a suggestion. Implementations may ignore it if it is not relevant for that + * particular implementation. All implementations must document their specific behavior for this method. + */ + fun stepInList(delimited: Boolean) + + /** + * Steps into a SExp. + * + * The [delimited] parameter is a suggestion. Implementations may ignore it if it is not relevant for that + * particular implementation. All implementations must document their specific behavior for this method. + */ + fun stepInSExp(delimited: Boolean) + + /** + * Steps into a Struct. + * + * The [delimited] and [useFlexSym] parameters are suggestions. Implementations may ignore these parameters if they + * are not relevant for that particular implementation. All implementations must document their specific behavior + * for this method. + */ + fun stepInStruct(delimited: Boolean, useFlexSym: Boolean) + + /** + * Steps into a stream. + * A stream is not a container in the Ion data model, but it is a container from an encoding perspective. + */ + fun stepInStream() + + /** + * Writes a macro invocation for the given macro name. + * A macro is not a container in the Ion data model, but it is a container from an encoding perspective. + */ + fun stepInEExp(name: CharSequence) + + /** + * Writes a macro invocation for the given id corresponding to a macro in the macro table. + * A macro is not a container in the Ion data model, but it is a container from an encoding perspective. + */ + fun stepInEExp(id: Int) + + /** + * Steps out of the current container. + */ + fun stepOut() + + // TODO: Doc comments for the uninteresting functions + + fun writeNull() + fun writeNull(type: IonType) + + fun writeBool(value: Boolean) + + fun writeInt(value: Byte) + fun writeInt(value: Int) + fun writeInt(value: Long) + fun writeInt(value: BigInteger) + + fun writeFloat(value: Float) + fun writeFloat(value: Double) + + fun writeDecimal(value: BigDecimal) + fun writeDecimal(value: Decimal) + + /** + * TODO: Consider adding a function for writing a timestamp that doesn't require creating a [Timestamp] instance, so + * that users don't have to allocate an intermediate between their data type and the Ion writer. E.g.: + * ``` + * fun writeTimestamp(precision: Timestamp.Precision, + * year: Int, month: Int?, day: Int?, + * hour: Int?, minute: Int?, second: Int?, + * fractionalSeconds: BigDecimal?, + * offsetMinutes: Int?) + * ``` + */ + fun writeTimestamp(value: Timestamp) + + /** Writes an Ion timestamp with 0 offset (UTC) and nanosecond precision. */ + fun writeTimestamp(value: Instant) + + fun writeSymbol(id: Int) + fun writeSymbol(text: CharSequence) + + fun writeString(value: CharSequence) + + fun writeBlob(value: ByteArray) = writeBlob(value, 0, value.size) + fun writeBlob(value: ByteArray, start: Int, length: Int) + + fun writeClob(value: ByteArray) = writeClob(value, 0, value.size) + fun writeClob(value: ByteArray, start: Int, length: Int) +}