avro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Amichai Rothman (JIRA)" <j...@apache.org>
Subject [jira] Updated: (AVRO-438) spec organization and clarification improvements
Date Tue, 23 Mar 2010 14:09:27 GMT

     [ https://issues.apache.org/jira/browse/AVRO-438?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Amichai Rothman updated AVRO-438:
---------------------------------

    Attachment: fix_map_verboseness.diff

np :-)

Here's a patch which reduces the apparent complexity of map encoding (previously several paragraphs
copy&pasted from array encoding description), if you like it. I think it's shorter to
read and simpler to understand. It's just semantics, so I've attached it here - I'll open
a separate report for the mime type issue.

> spec organization and clarification improvements
> ------------------------------------------------
>
>                 Key: AVRO-438
>                 URL: https://issues.apache.org/jira/browse/AVRO-438
>             Project: Avro
>          Issue Type: Improvement
>          Components: spec
>    Affects Versions: 1.3.0
>            Reporter: Amichai Rothman
>            Assignee: Amichai Rothman
>            Priority: Trivial
>             Fix For: 1.3.1
>
>         Attachments: fix_map_verboseness.diff, fix_spec_loose_ends.patch
>
>
> There are a few improvements that can be made to make the spec better organized and clarify
ambiguous meanings:
> 1. The binary encoding specifies string, then bytes, then longs. However, the first two
are dependent on the latter, so in essence long encoding is being used before it was defined.
In addition, string comes before bytes even though it is logically a special case of bytes.
It would be clearer if these were ordered long, bytes, string so that each definition builds
on its predecessors and nothing is used before it is defined. Maybe bytes/string should be
at the end of the other primitives, since they are technically more complex structures. Note
that it might be a good idea to do this in all places in the spec where primitives are enumerated.
> 2. The sentence about array count and size is a bit confusing. A possible alternative:
> "If a block's count is negative, its absolute value is used, and it is followed immediately
by a long  block size indicating the number of bytes in the block. "
> and maybe this should be immediately followed by the sentence explaining why this is
useful which is currently a few lines below.
> 3. There is a note about blocks being in experimental stage, but it's unclear if this
is only for map blocks or also for array blocks.
> 4. Object Container Files and Protocol Declarations are described in the spec using JSON
objects and their schema is shown, but it doesn't say anywhere how these should be serialized.
If it's using binary serialization, it should say so explicitly. If it can be either binary
or JSON, then the file has no self-describing way of differentiating the two - this should
be addressed somewhere (maybe have a different magic word for binary/JSON content).
> 5. Protocol Definition has a namespace and name (called protocol), but it is not clear
whether the namespace rules defined in the first section apply here or not. It should be mentioned
explicitly either way.
> 6.It would be extremely helpful to have a full sample of an RPC call over HTTP, possibly
using the HelloWorld protocol from the previous example. This would show how the transport,
framing, handshake, call format and messages all fit together. Examples in RFCs often help
clarify any misunderstandings that might arise from the body of the specs, which makes for
a better spec - and this would be great here too.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message