Support application implementation of IonWriter

[almann]

We need to stabilize the interface so applications can implement it.

Imported from ION-182,IONJAVA-160

[jonwilsdon]

We need to investigate if this is useful.

[san2488]

What is the guidance here? Is this interface stable enough to create custom implementations?

[raganhan]

Although the interface is fairly stable many places in ion-java explicitly expect one of the included implementations of IonWriter. So trying to use a custom implementation may result in a ClassCastException.

We are open to fixing this to allow custom implementations if there are valuable use cases for doing so.

[san2488]

Thanks. Can you give an example of where such an expectation is made?

I'm evaluating writing an implementation that would stream to S3 transparently. I was expecting to use IonValue.writeTo(IonWriter).

[raganhan]

IonWriter interface is intended to abstract away how to write Ion data in one of the serialization formats to an output source. A quote from its javadoc:

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.

Since S3 is an output source I don't think an IonWriter implementation is the correct abstraction here. Generally speaking an OutputStream implementation would be a better abstraction for an output source, e.g. file, in memory, socket.

I may be wrong here but AFAIK S3 does not support streaming. All its APIs require a content-length header so your component would need to fake the streaming behavior by buffering and sending complete objects to S3. For that I'd implementing something that sits on top of an IonWriter using it to write out values to the buffer ensuring that each ion document is valid with the necessary symbol tables.

That being said one example of the expectation I mentioned: https://github.com/amzn/ion-java/blob/master/src/software/amazon/ion/impl/lite/IonValueLite.java#L886. Important to note that there are many, many others.

[raganhan]

After talking to the team I'm closing this issue as we don't intend to allow a "from scratch" custom implementation of the IonWriter interface.

However we'd be open to provide a way for users to utilize the base capabilities of a writer, e.g. how to correctly write a binary Ion int, to build specialized writers with extra features for example triggering an action when some specific value is written. We are not sure how this capabilities would be exposed though as it would be better to design them with a user use case in mind.

[wsargent]

Is this javadoc comment still valid?

https://github.com/amzn/ion-java/blob/master/src/com/amazon/ion/IonWriter.java#L38

[dlurton]

Technically, no.

I would say that IonWriter is "stable" in the sense that it will remain source-compatible in future releases until at least the next major version bump and likely longer.

This library still doesn't support customer supplied implementations of the interface, however.