[
https://issues.apache.org/jira/browse/AVRO-769?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Scott Carey updated AVRO-769:
-----------------------------
Attachment: AVRO-769.v1.patch
Patch aligns the two APIs.
All construction of Encoders/Decoders go through EncoderFactory/DecoderFactory.
Configuration does when the constructor can be overloaded to do so -- with
BinaryEncoders and BinaryDecoders.
Other Encoders and Decoders require a Schema and common reinitialization would
not pass those in. These have their own configure() method, and only the Json
variants are public.
> Java: Align Decoder/Encoder APIs for consistency and long term stability
> -------------------------------------------------------------------------
>
> Key: AVRO-769
> URL: https://issues.apache.org/jira/browse/AVRO-769
> Project: Avro
> Issue Type: Improvement
> Components: java
> Reporter: Scott Carey
> Assignee: Scott Carey
> Priority: Blocker
> Fix For: 1.5.0
>
> Attachments: AVRO-769.v1.patch
>
>
> As part of AVRO-753, we modified the Encoder API to be more like the current
> Decoder API. This issue tracks related changes to solidify the API of both
> Encoder and Decoder to be more stable and consistent. It is expected that
> the result will be long-lived and not require major changes in the future for
> the following reasons:
> * Instantiation and configuration will be funneled through EncoderFactory and
> DecoderFactory. Individual implementation types and constructors are not
> exposed. With this abstraction we could, for example, put the features of
> BlockingBinaryEncoder into BufferedBinaryEncoder and not break any user code.
> We already have some of this distinction on the Decoder side, but not all
> BinaryDecoders are going through the factory.
> * The core Encoder and Decoder abstract classes will not declare
> configuration methods or constructors. This makes them 'pure' low level Avro
> read/write API constructs. This separation of concerns means, for example,
> that not all encoder implementations need wrap an OutputStream because of
> init(OutputStream out).
> * The core Encoder and Decoder API does not know or care about Schemas,
> resolution, or any other 'higher order' Avro concept. This is the pure
> separation of concern for writing/reading primitive Avro types to/from
> somewhere.
> * Implementations have been heavily performance tuned on both sides, so
> changes to the API necessary for high performance will not be likely.
> The Factories will adhere to the following general principles:
> * configuration options that do not affect the semantics of a type can be set
> through the factory. i.e. buffer sizes.
> * configuration that affects the semantics or changes the output or supported
> input will have separate factory methods. For example, choosing between an
> implementation that requires calling flush() and one that does not, requires
> choosing a different factory method to instantiate. This is important
> because it generally means that client code explicitly requests the
> behavioral type, and that helps prevent bugs caused by accidentally
> configuring a factory to return an object that is incompatible with the use
> case.
--
This message is automatically generated by JIRA.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
