This base class defines interface used for efficient encoding of typed values, by stream writers. The abstraction is necessary to reduce amount of duplicated code while avoiding significant additional overhead. The idea is that the low-level stream writer backend supplies encoder with the result buffer, while encoder itself knows the data and state. Together these allow for efficient serialization with light coupling.
General contract for encoding is that caller must call things in following sequence:
- First, {@link #bufferNeedsFlush} is called once; andif indicated by return value of true, caller must flush its buffer so it is completely empty (buffer also must have size of at at least
MIN_CHARS_WITHOUT_FLUSH) - Then, one of {@link #encodeMore} methods is to be called
- After this call, {@link #isCompleted} should be calledto determine if encoding was complete: if it was, there is nothing more to do.
- Otherwise caller should flush its buffer (since encoder has encoded as much as it can without flushing), and repeat cycle of calls to {@link #encodeMore} followedby a call to {@link #isCompleted} and flushing, as longas necessary to complete encoding.
Main restrictions for use are that value serializations must produce only 7-bit ascii characters, and that the value can be produced incrementally using limited size buffers. This is true for all current value types of the Typed Access API.
Finally, details of how encoders are created and/or reused is outside scope of this public interface. Stax2 reference implementation handles this using an encoder factory that knows construction details.
@since 3.0