avro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Scott Carey (JIRA)" <j...@apache.org>
Subject [jira] Created: (AVRO-769) Java: Align Decoder/Encoder APIs for consistency and long term stability
Date Thu, 17 Feb 2011 03:54:24 GMT
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
             Fix For: 1.5.0

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


View raw message