avro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From th...@apache.org
Subject svn commit: r1185027 [3/4] - in /avro/trunk: ./ lang/c++/ lang/c++/api/ lang/c++/api/buffer/ lang/c++/api/buffer/detail/ lang/c++/examples/
Date Mon, 17 Oct 2011 07:14:14 GMT
Modified: avro/trunk/lang/c++/MainPage.dox
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/MainPage.dox?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/MainPage.dox (original)
+++ avro/trunk/lang/c++/MainPage.dox Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -19,342 +19,289 @@
 /*!
 \mainpage
 
-\htmlonly
+<h2>Introduction to Avro C++</h2>
 
-<H2>Introduction to Avro C++</H2>
+<p>Avro is a data serialization system. See
+<a href="http://hadoop.apache.org/avro/docs/current/">http://avro.apache.org/docs/current/</a>
+for background information.</p>
+<p>Avro C++ is a C++ library which implementats parts of the <a href="http://avro.apache.org/docs/current/spec.html"> Avro Specification</a>. The library includes the following functionality:</p>
+<ul>
+	<li>Assembling schemas programmatically.
+    <li>A schema parser, which can parse Avro schema (written in JSON) into a Schema object.
+    <li>Encoders and decoders to encode data into Avro format and decode it back using primitive functions. There are multiple implementations of encoders and decoders.
+    <ul>
+        <li>A binary encoder, which encodes into binary Avro data.
+        <li>A JSON encoder, which encodes into JSON Avro data.
+        <li>A validating encoder, an encoder proxy, which validates the call sequence to the encoder before sending the calls to another encoder.
+        <li>A binary decoder, which decodes binay Avro data.
+        <li>A JSON decoder, which decodes JSON Avro data.
+        <li>A validating decoder, a decoder proxy, which validates the call sequence to the decoder before sending the calls to another decoder.
+        <li>A resolving decoder, which accepts calls for according to a reader's schema but decodes data corresponding to a different (writer's) schema doing schema resolution according to resolution rules in the Avro specification.
+    </ul>
+    <li>Streams for storing and reading data, which Encoders and Decoders use.
+    <li>Support for Avro DataFile.
+    <li>A code generator, which generates C++ classes fnd functions to encode and decode them. The code generator produces a C++ header file from a given schema file.
+</ul>
+Presently there is no support for the following specified in Avro specification.
+<ul>
+    <li>Avro RPC
+</ul>
+
+<b>Note:</b> Prior to Avro release 1.5, some of the functionality mentioned above was avilable through a somewhat different API and set tools. They are partially incompatible to the present ones. They continue to be available but will be deprecated and discontinued sometime in the future. The documentation on that API can be found at <a href="http://avro.apache.org/docs/1.4.0/api/cpp/html/index.html">http://avro.apache.org/docs/1.4.0/api/cpp/html/index.html</a> 
+
+<h2>Installing Avro C++</h2>
+<h3>Supported platforms and pre-requisites</h3>
+One should be able to build Avro C++ on any UNIX flavor including cygwin for Windows. We have tested it on Linux systems and Cygwin.
+
+In order to build Avro C++, one needs the following:
+<ul>
+    <li>A C++ compiler and runtime libraries.
+    <li>Boost library version 1.38 or later. Please see <a href="http://www.boost.org/">http://www.boost.org</a> or your platform's documentation for details on how to set up Boost for your platform.
+    <li>CMake build tool version 2.6 or later. Please see <a href="http://www.cmake.org">http://www.cmake.org</a> or your platform's documentation for details on how to set up CMake for your system.
+    <li>Flex and Bison. For many Linux systems, Flex and Bison are pre-installed. If your platforms does not have Flex or Bison, please install them.
+    <li>Python. If not already present, please consult your platform-specific documentation on how to install Python on your system.
+</ul>
+
+<h3>Installing Avro C++</h3>
+<ol>
+    <li>Download the latest Avro distribution. Avro distribution is a compressed tarball.
+Please see the main documentation if you want to build anything more than Avro C++. 
+    <li>Expand the tarball into a directory.
+    <li>Change to <tt>lang/c++</tt> subdirectory.
+    <li>Type <tt>./build.sh test</tt>. This builds Avro C++ and runs tests on it.
+    <li>Type <tt>./build.sh install</tt>. This installs Avro C++ under /usr/local on your system.
+</ol>
+
+
+<h2>Getting started with Avro C++</h2>
+
+<p>Although Avro does not require use of code generation, that is the easiest
+way to get started with the Avro C++ library.
+The code generator reads a schema, and generates a C++
+header file that defines one or more C++ <tt>struct</tt>s to represent
+the data for the schema and functions to encode and decode those
+<tt>struct</tt>s. Even if you wish to write custom code to encode and decode
+your objects using the core functionality of Avro C++, the generated code
+can serve as an example of how to use the code functionality.
+
+<p>
+Let's walk through an example, using a simple schema. Use the
+schema that represents an complex number:</p>
+
+<b>File: cpx.json</b>
+
+\includelineno cpx.json
+<p>
+<b>Note:</b> All the example code given here can be found under
+<tt>examples</tt> directory of the distribution.
 
-<P>Avro is a data serialization system. See
-<A HREF="http://hadoop.apache.org/avro/docs/current/">h</A><A HREF="http://hadoop.apache.org/avro/docs/current/">ttp://hadoop.apache.org/avro/docs/current/</A>
-for background information.</P>
-<P>This is the documentation for a C++ implementation of Avro. The
-library includes:</P>
-<UL>
-	<LI><P>objects for assembling schemas programmatically 
-	</P>
-	<LI><P>objects for reading and writing data, that may be used to
-	build custom serializers and parsers</P>
-	<LI><P>an object that validates the data against a schema during
-	serialization (used primarily for debugging)</P>
-	<LI><P>an object that reads a schema during parsing, and notifies
-	the reader which type (and name or other attributes) to expect next,
-	used for debugging or for building dynamic parsers that don't know a
-	priori which data to expect</P>
-	<LI><P>a code generation tool that creates C++ objects from a
-	schema, and the code to convert back and forth between the
-	serialized data and the object</P>
-	<LI><P>a parser that can convert data written in one schema to a C++
-	object with a different schema</P>
-</UL>
-
-<H2>Getting started with Avro C++</H2>
-
-<P>Although Avro does not require use of code generation, the easiest
-way to get started with the Avro C++ library is to use the code
-generation tool. The code generator reads a schema, and outputs a C++
-object to represent the data for the schema. It also creates the code
-to serialize this object, and to deserialize it... all the heavy
-coding is done for you. Even if you wish to write custom serializers
-or parsers using the core C++ libraries, the generated code can serve
-as an example of how to use these libraries.</P>
-<P>Let's walk through an example, using a simple schema. Use the
-schema that represents an imaginary number:</P>
-<PRE>{
-  &quot;type&quot;: &quot;record&quot;, 
-  &quot;name&quot;: &quot;complex&quot;,
-  &quot;fields&quot; : [
-    {&quot;name&quot;: &quot;real&quot;, &quot;type&quot;: &quot;double&quot;},    
-    {&quot;name&quot;: &quot;imaginary&quot;, &quot;type&quot; : &quot;double&quot;}
-  ]
-}</PRE><P>
+<p>
 Assume this JSON representation of the schema is stored in a file
-called imaginary. To generate the code is a two step process:</P>
-<PRE>precompile &lt; imaginary &gt; imaginary.flat</PRE><P>
-The precompile step converts the schema into an intermediate format
-that is used by the code generator. This intermediate file is just a
-text-based representation of the schema, flattened by a
-depth-first-traverse of the tree structure of the schema types.</P>
-<PRE>python scripts/gen-cppcode.py --input=example.flat --output=example.hh –-namespace=Math</PRE><P>
-This tells the code generator to read your flattened schema as its
-input, and generate a C++ header file in example.hh. The optional
-argument namespace will put the objects in that namespace (if you
-don't specify a namespace, you will still get a default namespace of
-avrouser).</P>
-<P>Here's the start of the generated code:</P>
-<PRE>namespace Math {
-
-struct complex {
-
-    complex () :
-        real(),
-        imaginary()
-    { } 
-
-    double real;
-    double imaginary;
-};</PRE><P>
-This is the C++ representation of the schema. It creates a structure
-for the record, a default constructor, and a member for each field of
-the record.</P>
-<P>There is some other output that we can ignore for now. Let's look
-at an example of serializing this data:</P>
-<PRE>void serializeMyData()
-{
-    Math::complex c;
-    c.real = 10.0;
-    c.imaginary = 20.0;
-
-    // Writer is the object that will do the actual I/O and buffer the results
-    avro::Writer writer;
-
-    // This will invoke the writer on my object
-    avro::serialize(writer, c);
-
-    // At this point, the writer stores the serialized data in a buffer,
-    // which can be extracted to an immutable buffer
-    InputBuffer buffer = writer.buffer();
-}</PRE><P>
-Using the generated code, all that is required to serialize the data
-is to call avro::serialize() on the object.</P>
-The data may be be accessed by requesting an avro::InputBuffer 
-object.  From there, it can be sent to a file, over the network, etc.</P>
-<P>Now let's do the inverse, and read the serialized data into our
-object:</P>
-<PRE>void parseMyData(const avro::InputBuffer &amp;myData)
-{
-    Math::complex c;
-
-    // Reader is the object that will do the actual I/O
-    avro::Reader reader(myData);
-
-    // This will invoke the reader on my object
-    avro::parse(reader, c);
-
-    // At this point, c is populated with the deserialized data!
-}</PRE><P>
-In case you're wondering how avro::serialize() and avro::parse()
-handled the custom data type, the answer is in the generated code. It
-created the following functions:</P>
-<PRE>template &lt;typename Serializer&gt;
-inline void serialize(Serializer &amp;s, const complex &amp;val, const boost::true_type &amp;) {
-    s.writeRecord();
-    serialize(s, val.real);
-    serialize(s, val.imaginary);
-    s.writeRecordEnd();
+called <tt>cpx.json</tt>. To generate the code issue the command:.
+<pre>
+avrogencpp -i cpx.json -o cpx.hh -n c
+</pre>
+The <tt>-i</tt> flag specifies the input schema file and <tt>-o</tt> flag
+specifies the output header file to generate. The generated C++ code will be
+in the namespace specifed with <tt>-n</tt> flag.
+
+<p>
+The generated file, among other things will have the following:
+
+<pre>
+
+...
+namespace c {
+...
+
+struct cpx {
+    double re;
+    double im;
+};
+
+
+...
+
 }
 
-template &lt;typename Parser&gt;
-inline void parse(Parser &amp;p, complex &amp;val, const boost::true_type &amp;) {
-    p.readRecord();
-    parse(p, val.real);
-    parse(p, val.imaginary);
-    p.readRecordEnd();
-}</PRE><P>
-It also adds the following to the avro namespace:</P>
-<PRE>template &lt;&gt; struct is_serializable&lt;Math::complex&gt; : public boost::true_type{};</PRE><P>
-This sets up a type trait for the complex structure, telling Avro
-that this object has serialize and parse functions available.</P>
+</pre>
+<tt>cpx</tt> is a C++ representation of the Avro schema <tt>cpx</tt>.
+
+Now let's see how we can use the code generated to encode data into avro and decode it back.
+
+<b>File: generated.cc</b>
 
-<H2>Reading a Json schema</H2>
+\includelineno generated.cc
 
-<P>The above section demonstrated pretty much all that's needed to
+In line 9, we construct a memory output stream. By this we indicate that we
+want to send the encoded Avro data into memory. In line 10, we construct a
+binary encoder, whereby we mean the output should be encoded using the Avro
+binary standard. In line 11, we attach the output stream to the encoder. At any given time an incoder can write to only one output stream.
+<p>
+In line 14, we write the contents of c1 into the output stream using the
+encoder. Now the output stream contains the binary representation of
+the object. The rest of the code verifies that the data is indeed in the stream.
+<p>
+In line 17, we construct a memory input stream from the contents of the
+output stream. Thus the input stream has the binary representation of the
+object. In line 18 and 19, we construct a binary decoder and attach the
+input stream to it. Line 22 decodes the contents of the stream into another
+object c2. Now c1 and c2 should have identical contents, which one can readily
+verify from the output of the program, which should be:
+
+<pre>
+(1, 2.13)
+</pre>
+
+Now, if you want to encode the data using Avro JSON encoding, you should use
+avro::jsonEncoder() instead of avro::binaryEncoder() in line 10
+and avro::jsonDecoder() instead of avro::binaryDecoder() in line 18.
+<p>
+
+On the other hand, if you want to write the contents to a file instead of
+memory, you should use avro::fileOutputStream() instead of
+avro::memoryOutputStream() in ine 9 and avro::fileInputStream()
+instead of avro::memoryInputStream() in line 17.
+<p>
+
+<h2>Reading a JSON schema</h2>
+
+<p>The section above demonstrated pretty much all that's needed to
 know to get started reading and writing objects using the Avro C++
 code generator. The following sections will cover some more
-information.</P>
-<P>The library provides some utilities to read a schema that is
-stored in a JSON file or string. Take a look:</P>
-<PRE>void readSchema()
-{
-    // My schema is stored in a file called “example”
-    std::ifstream in(“example”);
-
-    avro::ValidSchema mySchema;
-    avro::compileJsonSchema(in, mySchema);
-}
- </PRE><P>
-This reads the file, and parses the JSON schema into an object of
-type avro::ValidSchema. If, for some reason, the schema is not valid,
-the ValidSchema object will not be set, and an exception will be
+information.</p>
+<p>The library provides some utilities to read a schema that is
+stored in a JSON file:</p>
+
+<b>File: schemaload.cc</b>
+
+\includelineno schemaload.cc
+
+<p>
+This reads the file, and parses the JSON schema into an in-meory schema
+object of type avro::ValidSchema. If, for some reason, the schema is not valid,
+the <tt>cpxSchema</tt> object will not be set, and an exception will be
 thrown. 
-</P>
+</p>
+If you always use code Avro generator you don't really need the in-memory
+schema objects. But if you use custom objects and routines to encode or decode
+avro data, you will need the schema objects. Other uses of schema objects
+are generic data objects and schema resolution described in the following
+sections.
 
-<H2>To validate or not to validate</H2>
+<h2>Custom encoding and decoding</h2>
 
-<P>The last section showed how to create a ValidSchema object from a
-schema stored in JSON. You may wonder, what can I use the ValidSchema
-for?</P>
-<P>One use is to ensure that the writer is actually writing the types
-that match what the schema expects. Let's revisit the serialize
-function from above, but this time checking against our schema.</P>
-<PRE>void serializeMyData(const ValidSchema &amp;mySchema)
-{
-    Math::complex c;
-    c.real = 10.0;
-    c.imaginary = 20.0;
-
-    // ValidatingWriter will make sure our serializer is writing the correct types
-    avro::ValidatingWriter writer(mySchema);
-
-    try {
-        avro::serialize(writer, c);
-        // At this point, the ostringstream “os” stores the serialized data!
-    } 
-    catch (avro::Exception &amp;e) {
-        std::cerr &lt;&lt; “ValidatingWriter encountered an error: “ &lt;&lt; e.what();
-    }  
-}</PRE><P>
-The difference between this code and the previous version is that the
-Writer object was replaced with a ValidatingWriter. If the serializer
-function mistakenly writes a type that does not match the schema, the
-ValidatingWriter will throw an exception. 
-</P>
-<P>The ValidatingWriter will incur more processing overhead while
-writing your data. For the generated code, it's not necessary to use
-validation, because (hopefully!) the mechanically generated code will
-match the schema. Nevertheless it is nice while debugging to have the
-added safety of validation, especially when writing and testing your
-own serializing code.</P>
-<P>The ValidSchema may also be used when parsing data. In addition to
-making sure that the parser reads types that match the schema, it
-provides an interface to query the next type to expect, and the
-field's name if it is a member of a record.</P>
-<P>The following code is not very flexible, but it does demonstrate
-the API:</P>
-<PRE>void parseMyData(const avro::InputBuffer &amp;myData, const avro::ValidSchema &amp;mySchema)
-{
-    // Manually parse data, the Parser object binds the data to the schema
-    avro::Parser&lt;ValidatingReader&gt; parser(mySchema, myData);
-
-    assert( nextType(parser) == avro::AVRO_RECORD);
-    
-    // Begin parsing
-    parser.readRecord();
-   
-    Math::complex c;
-
-    std::string recordName;
-    assert( currentRecordName(parser, recordName) == true);
-    assert( recordName == “complex”);
-    std::string fieldName;
-    for(int i=0; i &lt; 2; ++i) {
-        assert( nextType(parser) == avro::AVRO_DOUBLE);
-        assert( nextFieldName(parser, fieldName) == true);
-        if(fieldName == “real”) {
-            c.real = parser.readDouble();
-        } 
-        else if (fieldName == “imaginary”) {
-            c.imaginary = parser.readDouble();
-        } 
-        else {
-            std::cout &lt;&lt; “I did not expect that!\n”;
-        }
-    }
-
-    parser.readRecordEnd();
-}</PRE><P>
-The above code shows that if you don't know the schema at compile
-time, you can still write code that parses the data, by reading the
-schema at runtime and querying the ValidatingReader to discover what
-is in the serialized data.</P>
-
-<H2>Programmatically creating schemas</H2>
-
-<P>You can use objects to create schemas in your code. There are
-schema objects for each primitive and compound type, and they all
-share a common base class called Schema.</P>
-<P>Here's an example, of creating a schema for an array of records of
-complex data types:</P>
-<PRE>void createMySchema()
-{
-    // First construct our complex data type:
-    avro::RecordSchema myRecord(“complex”);
-   
-    // Now populate my record with fields (each field is another schema):
-    myRecord.addField(“real”, avro::DoubleSchema());
-    myRecord.addField(“imaginary”, avro::DoubleSchema());
-
-    // The complex record is the same as used above, let's make a schema 
-    // for an array of these record
-  
-    avro::ArraySchema complexArray(myRecord); </PRE><P>
-The above code created our schema, but at this point it is possible
-that a schema is not valid (a record may not have any fields, or some
-field names may not be unique, etc.) In order to use the schema, you
-need to convert it to the ValidSchema object:</P>
-<PRE>   // this will throw if the schema is invalid!
-   avro::ValidSchema validComplexArray(complexArray);
-
-   // now that I have my schema, what does it look like in JSON?
-   // print it to the screen
-   validComplexArray.toJson(std::cout);
-}</PRE><P>
-When the above code executes, it prints:</P>
-<PRE>{
-    &quot;type&quot;: &quot;array&quot;,
-    &quot;items&quot;: {
-        &quot;type&quot;: &quot;record&quot;,
-        &quot;name&quot;: &quot;complex&quot;,
-        &quot;fields&quot;: [
-            {
-                &quot;name&quot;: &quot;real&quot;,
-                &quot;type&quot;: &quot;double&quot; 
-            },
-            {
-                &quot;name&quot;: &quot;imaginary&quot;,
-                &quot;type&quot;: &quot;double&quot; 
-            } 
-        ]
-    }
-}
-</PRE>
+Suppose you want to encode objects of type std::complex<double> from
+C++ standard library using the schema defined in cpx.json.
+Since std::complex<double> was not generated by Avro, it does't know how to encode or decode objects of that
+type. You have to tell Avro how to do that.
 
-<H2>Converting from one schema to another</H2>
+The recommended way to tell Avro how to encode or decode is to specialize
+Avro's codec_traits template. For std::complex<double>, here is what you'd do:
 
-<P>The Avro spec provides rules for dealing with schemas that are not
-exactly the same (for example, the schema may evolve over time, and
-the data my program now expects may differ than the data stored
-previously with the older version).</P>
-<P>The code generation tool may help again in this case.  For each
-structure it generates, it creates a special indexing structure that
-may be used to read the data, even if the data was written with a
-different schema.</P>
-<P>In example.hh, this indexing structure looks like:</P>
-<PRE>class complex_Layout : public avro::CompoundOffset {
-  public:
-    complex_Layout(size_t offset) :
-        CompoundOffset(offset)
-    {
-        add(new avro::Offset(offset + offsetof(complex, real)));
-        add(new avro::Offset(offset + offsetof(complex, imaginary)));
-    }
-}; 
-</PRE>
-<P>Let's say my data was previously written with floats instead of
-doubles.  According the schema resolution rules, the schemas are
-compatible, because floats are promotable to doubles.  As long as
-both the old and the new schemas are available, a dynamic parser may
-be created that reads the data to the code generated structure.</P>
-<PRE>void dynamicParse(const avro::ValidSchema &amp;writerSchema, 
-                  const avro::ValidSchema &amp;readerSchema) {
-
-    // Instantiate the Layout object
-    Math::complex_Layout layout;
-
-    // Create a schema parser that is aware of my type's layout, and both schemas
-    avro::ResolverSchema resolverSchema(writerSchema, readerSchema, layout);
-
-    // Setup the reader
-    avro::ResolvingReader reader(resolverSchema, data);
-
-    Math::complex c;
-    
-    // Do the parse
-    avro::parse(reader, c);
+<b>File: custom.cc</b>
 
-    // At this point, c is populated with the deserialized data!
-}
-</PRE>
+\includelineno custom.cc
+
+Please notice that the main function is pretty much similar to that we used
+for the generated class. Once <tt>codec_traits</tt> for a specific type is
+supplied, you do not really need to do anything special for your custom types.
+
+<p>
+
+But wait, how does Avro know that complex<double> represents the data for
+the schema in <tt>cpx.json</tt>? It doesn't. In fact, if you have used
+<tt>std::complex<float></tt> instead of <tt>std::complex<double></tt> program
+would have worked. But the data in the memory would not have been corresponding
+to the schema in <tt>cpx.json</tt>.
+
+<p>
+
+In order to ensure that you indeed use the correct type, you can use
+the validating encoders and decoder. Here is how:
+
+<b>File: validating.cc</b>
+
+\includelineno validating.cc
+
+Here, instead of using the plain binary encoder, you use a validating encoder
+backed by a binary encoder. Similarly, instead of using the plain binary
+decoder, you use a validating decoder backed by a binary decoder. Now,
+if you use <tt>std::complex<float></tt> intead of <tt>std::complex<double></tt>
+the validating encoder and decoder will throw exception stating that
+you are trying to encode or decode <tt>float</tt> instead of <tt>double</tt>.
+<p>
+You can use any encoder behind the validating encoder and any decoder
+behind the validating decoder. But in practice, only the binary encoder
+and the binary decoder have no knowledge of the underlying schema.
+All other encoders (JSON encoder) and decoders (JSON decoder,
+resolving decoder) do know about the schema and they validate internally. So,
+fronting them with a validating encoder or validating decoder is wasteful.
+
+<h2>Generic data objects</h2>
+
+A third way to encode and decode data is to use Avro's generic datum.
+Avro's generic datum allows you to read any arbitray data corresponding to
+an arbitrary schema into a generic object. One need not know anything
+about the schema or data at complie time. 
+
+Here is an example how one can use the generic datum.
+
+<b>File: generic.cc</b>
+
+\includelineno generic.cc
+
+In this example, we encode the data using generated code and decode it with
+generic datum. Then we examine the contents of the generic datum and extract
+them. Please see \ref avro::GenericDatum for more details on how to use it.
+
+<h2>Reading data with a schema different from that of the writer</h2>
+It is possible to read the data written according to one schema
+using a different schema, provided the reader's schema and the writer's
+schema are compatible according to the Avro's Schema resolution rules. 
+<p>
+For example, you have a reader which is interested only in the imaginary part
+of a complex number while the writer writes both the real and imaginary parts.
+It is possible to do automatic schema resolution between the writer's schema
+and schema as shown below.
+
+<b>File: imaginary.json</b>
+
+\includelineno imaginary.json
+
+<pre>
+avrogencpp -i imaginary.json -o imaginary.hh -n i
+</pre>
+
+<b>File: resolving.cc</b>
+
+\includelineno resolving.cc
+
+In this example, writer and reader deal with different schemas,
+both are recornd with the same name cpx. The writer schema has two fields and
+the reader's has just one. We generated code for writer's schema in a namespace
+<tt>c</tt> and the reader's in <tt>i</tt>.
+
+<p>
+Please notice how the reading part of the example at line 42 reads as if
+the stream contains the data corresponding to its schema. The schema resolution
+is automatically done by the resolving decoder.
+
+<p>
+In this example, we have used a simple (somewhat artificial) projection (where the set of fields in
+the reader's schema is a subset of set of fields in the writer's). But more
+complex resolutions are allowed by Avro specification.
+
+<h2>Using Avro data files</h2>
+Avro specification specifies a format for data files. Avro C++ implements
+the sepcification. The code below demonstrates how one can use the
+Avro data file to store and retrieve a collection of objects
+corresponding to a given schema.
+
+<b>File: datafile.cc</b>
 
-\endhtmlonly
+\includelineno datafile.cc
 
+Please see DataFile.hh for more details.
 */
 

Modified: avro/trunk/lang/c++/api/AvroParse.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/AvroParse.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/AvroParse.hh (original)
+++ avro/trunk/lang/c++/api/AvroParse.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/AvroSerialize.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/AvroSerialize.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/AvroSerialize.hh (original)
+++ avro/trunk/lang/c++/api/AvroSerialize.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/AvroTraits.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/AvroTraits.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/AvroTraits.hh (original)
+++ avro/trunk/lang/c++/api/AvroTraits.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Boost.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Boost.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Boost.hh (original)
+++ avro/trunk/lang/c++/api/Boost.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Compiler.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Compiler.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Compiler.hh (original)
+++ avro/trunk/lang/c++/api/Compiler.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/CompilerNode.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/CompilerNode.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/CompilerNode.hh (original)
+++ avro/trunk/lang/c++/api/CompilerNode.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/DataFile.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/DataFile.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/DataFile.hh (original)
+++ avro/trunk/lang/c++/api/DataFile.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -34,6 +34,9 @@
 
 namespace avro {
 
+/**
+ * The sync value.
+ */
 typedef boost::array<uint8_t, 16> DataFileSync;
 
 /**
@@ -68,10 +71,20 @@ class DataFileWriterBase : boost::noncop
     void sync();
 
 public:
+    /**
+     * Returns the current encoder for this writer.
+     */
     Encoder& encoder() const { return *encoderPtr_; }
     
+    /**
+     * Returns true if the buffer has sufficient data for a sync to be
+     * inserted.
+     */
     void syncIfNeeded();
 
+    /**
+     * Increments the object count.
+     */
     void incr() {
         ++objectCount_;
     }
@@ -139,6 +152,9 @@ public:
     void flush() { base_->flush(); }
 };
 
+/**
+ * The type independent portion of rader.
+ */
 class DataFileReaderBase : boost::noncopyable {
     const std::string filename_;
     const std::auto_ptr<InputStream> stream_;
@@ -158,6 +174,9 @@ class DataFileReaderBase : boost::noncop
 
     bool readDataBlock();
 public:
+    /**
+     * Returns the current decoder for this reader.
+     */
     Decoder& decoder() { return *dataDecoder_; }
 
     /**
@@ -165,6 +184,9 @@ public:
      */
     bool hasMore();
 
+    /**
+     * Decrements the number of objects yet to read.
+     */
     void decr() { --objectCount_; }
 
     /**
@@ -206,6 +228,9 @@ public:
     void close();
 };
 
+/**
+ * Reads the contents of data file one after another.
+ */
 template <typename T>
 class DataFileReader : boost::noncopyable {
     std::auto_ptr<DataFileReaderBase> base_;
@@ -256,6 +281,11 @@ public:
         base_->init(readerSchema);
     }
 
+    /**
+     * Reads the next entry from the data file.
+     * \return true if an object has been successfully read into \p datum and
+     * false if there are no more entries in the file.
+     */
     bool read(T& datum) {
         if (base_->hasMore()) {
             base_->decr();

Modified: avro/trunk/lang/c++/api/Decoder.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Decoder.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Decoder.hh (original)
+++ avro/trunk/lang/c++/api/Decoder.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -41,6 +41,10 @@
 
 namespace avro {
 
+/**
+ * Decoder is an interface implemented by every decoder capable
+ * of decoding Avro data.
+ */
 class Decoder {
 public:
     /// All future decoding will come from is, which should be valid
@@ -95,13 +99,24 @@ public:
     /// Skips bytes on the current stream.
     virtual void skipBytes() = 0;
 
-    /// Decodes fixed length binary from the current stream.
+    /**
+     * Decodes fixed length binary from the current stream.
+     * \param[in] n The size (byte count) of the fixed being read.
+     * \return The fixed data that has been read. The size of the returned
+     * vector is guaranteed to be equal to \p n.
+     */
     std::vector<uint8_t> decodeFixed(size_t n) {
         std::vector<uint8_t> result;
         decodeFixed(n, result);
         return result;
     }
 
+    /**
+     * Decodes a fixed from the current stream.
+     * \param[in] n The size (byte count) of the fixed being read.
+     * \param[out] value The value that receives the fixed. The vector will
+     * be size-adjusted based on the fixed's size.
+     */
     virtual void decodeFixed(size_t n, std::vector<uint8_t>& value) = 0;
 
     /// Skips fixed length binary on the current stream.
@@ -138,8 +153,15 @@ public:
     virtual size_t decodeUnionIndex() = 0;
 };
 
+/**
+ * Shared pointer to Decoder.
+ */
 typedef boost::shared_ptr<Decoder> DecoderPtr;
 
+/**
+ * ResolvingDecoder is derived from \ref Decoder, with an additional
+ * function to obtain the field ordering of fiedls within a record.
+ */
 class ResolvingDecoder : public Decoder {
 public:
     /// Returns the order of fields for records.
@@ -150,6 +172,9 @@ public:
     virtual const std::vector<size_t>& fieldOrder() = 0;
 };
 
+/**
+ * Shared pointer to ResolvingDecoder.
+ */
 typedef boost::shared_ptr<ResolvingDecoder> ResolvingDecoderPtr;
 /**
  *  Returns an decoder that can decode binary Avro standard.

Modified: avro/trunk/lang/c++/api/Encoder.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Encoder.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Encoder.hh (original)
+++ avro/trunk/lang/c++/api/Encoder.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -44,6 +44,11 @@
 
 namespace avro {
 
+/**
+ * The abstract base class for all Avro encoders. The implementations
+ * differ in the method of encoding (binary vresus JSON) or in capabilities
+ * such as ability to verify the order of invocation of different functions.
+ */
 class Encoder {
 public:
     /// All future encodings will go to os, which should be valid until
@@ -75,9 +80,19 @@ public:
     /// Encodes a UTF-8 string to the current stream.
     virtual void encodeString(const std::string& s) = 0;
 
-    /// Encodes arbitray binary data to the current stream.
+    /**
+     * Encodes aribtray binary data into tthe current stream as Avro "bytes"
+     * data type.
+     * \param bytes Where the data is
+     * \param len Number of bytes at \p bytes.
+     */
     virtual void encodeBytes(const uint8_t *bytes, size_t len) = 0;
 
+    /**
+     * Encodes aribtray binary data into tthe current stream as Avro "bytes"
+     * data type.
+     * \param bytes The data.
+     */
     void encodeBytes(const std::vector<uint8_t>& bytes) {
         encodeBytes(&bytes[0], bytes.size());
     }
@@ -85,6 +100,11 @@ public:
     /// Encodes fixed length binary to the current stream.
     virtual void encodeFixed(const uint8_t *bytes, size_t len) = 0;
 
+    /**
+     * Encodes an Avro data type Fixed.
+     * \param bytes The fixed, the length of which is taken as the size
+     * of fixed.
+     */
     void encodeFixed(const std::vector<uint8_t>& bytes) {
         encodeFixed(&bytes[0], bytes.size());
     }
@@ -115,6 +135,9 @@ public:
     virtual void encodeUnionIndex(size_t e) = 0;
 };
 
+/**
+ * Shared pointer to Encoder.
+ */
 typedef boost::shared_ptr<Encoder> EncoderPtr;
 
 /**

Modified: avro/trunk/lang/c++/api/Exception.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Exception.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Exception.hh (original)
+++ avro/trunk/lang/c++/api/Exception.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Generic.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Generic.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Generic.hh (original)
+++ avro/trunk/lang/c++/api/Generic.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -34,6 +34,28 @@
 
 namespace avro {
 
+/**
+ * Generic datum which can hold any Avro type. The datum has a type
+ * and a value. The type is one of the Avro data types. The C++ type for
+ * value corresponds to the Avro type.
+ * \li An Avro <tt>null</tt> corresponds to no C++ type. It is illegal to
+ * to try to access values for <tt>null</tt>.
+ * \li Avro <tt>boolean</tt> maps to C++ <tt>bool</tt>
+ * \li Avro <tt>int</tt> maps to C++ <tt>int32_t</tt>.
+ * \li Avro <tt>long</tt> maps to C++ <tt>int64_t</tt>.
+ * \li Avro <tt>float</tt> maps to C++ <tt>float</tt>.
+ * \li Avro <tt>double</tt> maps to C++ <tt>double</tt>.
+ * \li Avro <tt>string</tt> maps to C++ <tt>std::string</tt>.
+ * \li Avro <tt>bytes</tt> maps to C++ <tt>std::vector&lt;uint_t&gt;</tt>.
+ * \li Avro <tt>fixed</tt> maps to C++ class <tt>GenericFixed</tt>.
+ * \li Avro <tt>enum</tt> maps to C++ class <tt>GenericEnum</tt>.
+ * \li Avro <tt>array</tt> maps to C++ class <tt>GenericArray</tt>.
+ * \li Avro <tt>map</tt> maps to C++ class <tt>GenericMap</tt>.
+ * \li There is no C++ type corresponding to Avro <tt>union</tt>. The
+ * object should have the C++ type corresponing to one of the constituent
+ * types of the union.
+ *
+ */
 class GenericDatum {
     Type type_;
     boost::any value_;
@@ -44,15 +66,32 @@ class GenericDatum {
     GenericDatum(Type t, const T& v) : type_(t), value_(v) { }
 
 public:
+    /**
+     * The avro data type this datum holds.
+     */
     Type type() const {
         return type_;
     }
 
+    /**
+     * Returns the value held by this datum.
+     * T The type for the value. This must correspond to the
+     * avro type returned by type().
+     */
     template<typename T>
     const T& value() const {
         return *boost::any_cast<T>(&value_);
     }
 
+    /**
+     * Returns the reference to the value held by this datum, which
+     * can be used to change the contents. Please note that only
+     * value can be changed, the data type of the value held cannot
+     * be changed.
+     *
+     * T The type for the value. This must correspond to the
+     * avro type returned by type().
+     */
     template<typename T>
     T& value() {
         return *boost::any_cast<T>(&value_);
@@ -84,15 +123,35 @@ public:
     GenericDatum(const std::vector<uint8_t>& v) :
         type_(AVRO_BYTES), value_(v) { }
 
+    /**
+     * Constructs a datum corresponding to the given avro type.
+     * The value will the appropraite default corresponding to the
+     * data type.
+     * \param schema The schema that defines the avro type.
+     */
     GenericDatum(const NodePtr& schema);
 };
 
+/**
+ * The base class for all generic type for containers.
+ */
 class GenericContainer {
     const NodePtr schema_;
 protected:
+    /**
+     * Constructs a container corresponding to the given schema.
+     */
     GenericContainer(const NodePtr& s) : schema_(s) { }
 
+    /**
+     * Asserts if the given generic datum \p v has a type that matches \p n.
+     */
     static void assertSameType(const GenericDatum& v, const NodePtr& n);
+
+    /**
+     * Asserts that the given schema \p schema has the given type \c type.
+     * If not, it throws an exception with the given message \c message.
+     */
     static void assertType(const NodePtr& schema, Type type,
         const char* message);
 public:
@@ -102,43 +161,79 @@ public:
     }
 };
 
+/**
+ * The generic container for Avro records.
+ */
 class GenericRecord : public GenericContainer {
     std::vector<GenericDatum> fields_;
 public:
+    /**
+     * Constructs a generic record corresponding to the given schema \p schema,
+     * which should be of Avro type record.
+     */
     GenericRecord(const NodePtr& schema);
 
+    /**
+     * Returns the number of fields in the current record.
+     */
     size_t fieldCount() const {
         return fields_.size();
     }
 
+    /**
+     * Returns the field at the given position \p pos.
+     */
     const GenericDatum& fieldAt(size_t pos) const {
         return fields_[pos];
     }
 
+    /**
+     * Returns the reference to the field at the given position \p pos,
+     * which can be used to change the contents.
+     */
     GenericDatum& fieldAt(size_t pos) {
         return fields_[pos];
     }
 
+    /**
+     * Replaces the field at the given position \p pos with \p v.
+     */
     void setFieldAt(size_t pos, const GenericDatum& v) {
         assertSameType(v, schema()->leafAt(pos));    
         fields_[pos] = v;
     }
 };
 
+/**
+ * The generic container for Avro arrays.
+ */
 class GenericArray : public GenericContainer {
 public:
+    /**
+     * The contents type for the array.
+     */
     typedef std::vector<GenericDatum> Value;
 
+    /**
+     * Constructs a generic array corresponding to the given schema \p schema,
+     * which should be of Avro type array.
+     */
     GenericArray(const NodePtr& schema) : GenericContainer(schema) {
         if (schema->type() != AVRO_ARRAY) {
             throw Exception("Schema is not an array");
         }
     }
 
+    /**
+     * Returns the contents of this array.
+     */
     const Value& value() const {
         return value_;
     }
 
+    /**
+     * Returns the reference to the contents of this array.
+     */
     Value& value() {
         return value_;
     }
@@ -146,18 +241,34 @@ private:
     Value value_;
 };
 
+/**
+ * The generic container for Avro maps.
+ */
 class GenericMap : public GenericContainer {
 public:
+    /**
+     * The contents type for the map.
+     */
     typedef std::vector<std::pair<std::string, GenericDatum> > Value;
 
+    /**
+     * Constructs a generic map corresponding to the given schema \p schema,
+     * which should be of Avro type map.
+     */
     GenericMap(const NodePtr& schema) : GenericContainer(schema) {
         assertType(schema, AVRO_MAP, "Schema is not a map");
     }
 
+    /**
+     * Returns the contents of this map.
+     */
     const Value& value() const {
         return value_;
     }
 
+    /**
+     * Returns the reference to the contents of this map.
+     */
     Value& value() {
         return value_;
     }
@@ -165,12 +276,23 @@ private:
     Value value_;
 };
 
+/**
+ * Generic container for Avro enum.
+ */
 class GenericEnum : public GenericContainer {
     size_t value_;
 public:
+    /**
+     * Constructs a generic enum corresponding to the given schema \p schema,
+     * which should be of Avro type enum.
+     */
     GenericEnum(const NodePtr& schema) : GenericContainer(schema), value_(0) {
     }
 
+    /**
+     * Returns the symbol corresponding to the cardinal \p n. If the
+     * value for \p n is not within the limits an exception is thrown.
+     */
     const std::string& symbol(size_t n) {
         if (n < schema()->names()) {
             return schema()->nameAt(n);
@@ -178,6 +300,10 @@ public:
         throw Exception("Not as many symbols");
     }
 
+    /**
+     * Returns the cardinal for the given symbol \c symbol. If the symbol
+     * is not defined for this enum and exception is thrown.
+     */
     size_t index(const std::string& symbol) const {
         size_t result;
         if (schema()->nameIndex(symbol, result)) {
@@ -186,10 +312,16 @@ public:
         throw Exception("No such symbol");
     }
 
+    /**
+     * Set the value for this enum corresponding to the given symbol \c symbol.
+     */
     size_t set(const std::string& symbol) {
         return value_ = index(symbol);
     }
 
+    /**
+     * Set the value for this enum corresponding to the given cardinal \c n.
+     */
     void set(size_t n) {
         if (n < schema()->names()) {
             value_ = n;
@@ -198,32 +330,54 @@ public:
         throw Exception("Not as many symbols");
     }
 
+    /**
+     * Returns the cardinal for the current value of this enum.
+     */
     size_t value() const {
         return value_;
     }
 
+    /**
+     * Returns the symbol for the current value of this enum.
+     */
     const std::string& symbol() const {
         return schema()->nameAt(value_);
     }
 };
 
+/**
+ * Generic container for Avro fixed.
+ */
 class GenericFixed : public GenericContainer {
     std::vector<uint8_t> value_;
 public:
+    /**
+     * Constructs a generic enum corresponding to the given schema \p schema,
+     * which should be of Avro type fixed.
+     */
     GenericFixed(const NodePtr& schema) : GenericContainer(schema) {
         value_.resize(schema->fixedSize());
     }
 
+    /**
+     * Returns the contents of this fixed.
+     */
     const std::vector<uint8_t>& value() const {
         return value_;
     }
 
+    /**
+     * Returns the reference to the contents of this fixed.
+     */
     std::vector<uint8_t>& value() {
         return value_;
     }
 };
 
 
+/**
+ * A utility class to read generic datum from decoders.
+ */
 class GenericReader : boost::noncopyable {
     const ValidSchema schema_;
     const bool isResolving_;
@@ -232,10 +386,22 @@ class GenericReader : boost::noncopyable
     static void read(GenericDatum& datum, const NodePtr& n, Decoder& d,
         bool isResolving);
 public:
+    /**
+     * Constructs a reader for the given schema using the given decoder.
+     */
     GenericReader(const ValidSchema& s, const DecoderPtr& decoder);
+
+    /**
+     * Constructs a reader for the given reader's schema \c readerSchema
+     * using the given
+     * decoder which holds data matching writer's schema \c writerSchema.
+     */
     GenericReader(const ValidSchema& writerSchema,
         const ValidSchema& readerSchema, const DecoderPtr& decoder);
 
+    /**
+     * Reads a value off the decoder.
+     */
     void read(GenericDatum& datum) const;
 
     /**
@@ -245,14 +411,23 @@ public:
 };
 
 
+/**
+ * A utility class to write generic datum to encoders.
+ */
 class GenericWriter : boost::noncopyable {
     const ValidSchema schema_;
     const EncoderPtr encoder_;
 
     static void write(const GenericDatum& datum, const NodePtr& n, Encoder& e);
 public:
+    /**
+     * Constructs a writer for the given schema using the given encoder.
+     */
     GenericWriter(const ValidSchema& s, const EncoderPtr& encoder);
 
+    /**
+     * Writes a value onto the encoder.
+     */
     void write(const GenericDatum& datum) const;
 
     /**
@@ -263,12 +438,17 @@ public:
 
 template <typename T> struct codec_traits;
 
+/**
+ * Specialization for codec_traits for Generic datum.
+ */
 template <> struct codec_traits<std::pair<ValidSchema, GenericDatum> > {
+    /** Encodes */
     static void encode(Encoder& e,
         const std::pair<ValidSchema, GenericDatum>& p) {
         GenericWriter::write(e, p.second, p.first);
     }
 
+    /** Decodes */
     static void decode(Decoder& d, std::pair<ValidSchema, GenericDatum>& p) {
         GenericReader::read(d, p.second, p.first);
     }

Modified: avro/trunk/lang/c++/api/Layout.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Layout.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Layout.hh (original)
+++ avro/trunk/lang/c++/api/Layout.hh Mon Oct 17 07:14:12 2011
@@ -1,5 +1,4 @@
-
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Node.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Node.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Node.hh (original)
+++ avro/trunk/lang/c++/api/Node.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/NodeConcepts.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/NodeConcepts.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/NodeConcepts.hh (original)
+++ avro/trunk/lang/c++/api/NodeConcepts.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/NodeImpl.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/NodeImpl.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/NodeImpl.hh (original)
+++ avro/trunk/lang/c++/api/NodeImpl.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Parser.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Parser.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Parser.hh (original)
+++ avro/trunk/lang/c++/api/Parser.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Reader.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Reader.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Reader.hh (original)
+++ avro/trunk/lang/c++/api/Reader.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Resolver.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Resolver.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Resolver.hh (original)
+++ avro/trunk/lang/c++/api/Resolver.hh Mon Oct 17 07:14:12 2011
@@ -1,5 +1,4 @@
-
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/ResolverSchema.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/ResolverSchema.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/ResolverSchema.hh (original)
+++ avro/trunk/lang/c++/api/ResolverSchema.hh Mon Oct 17 07:14:12 2011
@@ -1,5 +1,4 @@
-
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/ResolvingReader.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/ResolvingReader.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/ResolvingReader.hh (original)
+++ avro/trunk/lang/c++/api/ResolvingReader.hh Mon Oct 17 07:14:12 2011
@@ -1,5 +1,4 @@
-
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Schema.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Schema.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Schema.hh (original)
+++ avro/trunk/lang/c++/api/Schema.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/SchemaResolution.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/SchemaResolution.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/SchemaResolution.hh (original)
+++ avro/trunk/lang/c++/api/SchemaResolution.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Serializer.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Serializer.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Serializer.hh (original)
+++ avro/trunk/lang/c++/api/Serializer.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Specific.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Specific.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Specific.hh (original)
+++ avro/trunk/lang/c++/api/Specific.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -48,85 +48,165 @@ namespace avro {
 template <typename T> void encode(Encoder& e, const T& t);
 template <typename T> void decode(Decoder& d, T& t);
 
+/**
+ * Codec_traits tells avro how to encode and decode an object of given type.
+ *
+ * The class is expected to have two static methods:
+ * \li static void encode(Encoder& e, const T& value);
+ * \li static void decode(Decoder& e, T& value);
+ * The default is empty.
+ */
 template <typename T>
 struct codec_traits {
 };
 
+/**
+ * codec_traits for Avro boolean.
+ */
 template <> struct codec_traits<bool> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, bool b) {
         e.encodeBool(b);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, bool& b) {
         b = d.decodeBool();
     }
 };
 
+/**
+ * codec_traits for Avro int.
+ */
 template <> struct codec_traits<int32_t> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, int32_t i) {
         e.encodeInt(i);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, int32_t& i) {
         i = d.decodeInt();
     }
 };
 
+/**
+ * codec_traits for Avro long.
+ */
 template <> struct codec_traits<int64_t> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, int64_t l) {
         e.encodeLong(l);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, int64_t& l) {
         l = d.decodeLong();
     }
 };
 
+/**
+ * codec_traits for Avro float.
+ */
 template <> struct codec_traits<float> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, float f) {
         e.encodeFloat(f);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, float& f) {
         f = d.decodeFloat();
     }
 };
 
+/**
+ * codec_traits for Avro double.
+ */
 template <> struct codec_traits<double> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, double d) {
         e.encodeDouble(d);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, double& dbl) {
         dbl = d.decodeDouble();
     }
 };
 
+/**
+ * codec_traits for Avro string.
+ */
 template <> struct codec_traits<std::string> {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, const std::string& s) {
         e.encodeString(s);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, std::string& s) {
         s = d.decodeString();
     }
 };
 
+/**
+ * codec_traits for Avro bytes.
+ */
 template <> struct codec_traits<std::vector<uint8_t> > {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, const std::vector<uint8_t>& b) {
         e.encodeBytes(b);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, std::vector<uint8_t>& s) {
         d.decodeBytes(s);
     }
 };
 
+/**
+ * codec_traits for Avro fixed.
+ */
 template <size_t N> struct codec_traits<boost::array<uint8_t, N> > {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, const boost::array<uint8_t, N>& b) {
         e.encodeFixed(&b[0], N);
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, boost::array<uint8_t, N>& s) {
         std::vector<uint8_t> v(N);
         d.decodeFixed(N, v);
@@ -134,7 +214,13 @@ template <size_t N> struct codec_traits<
     }
 };
 
+/**
+ * codec_traits for Avro arrays.
+ */
 template <typename T> struct codec_traits<std::vector<T> > {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, const std::vector<T>& b) {
         e.arrayStart();
         if (! b.empty()) {
@@ -148,6 +234,9 @@ template <typename T> struct codec_trait
         e.arrayEnd();
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, std::vector<T>& s) {
         s.clear();
         for (size_t n = d.arrayStart(); n != 0; n = d.arrayNext()) {
@@ -160,7 +249,13 @@ template <typename T> struct codec_trait
     }
 };
 
+/**
+ * codec_traits for Avro maps.
+ */
 template <typename T> struct codec_traits<std::map<std::string, T> > {
+    /**
+     * Encodes a given value.
+     */
     static void encode(Encoder& e, const std::map<std::string, T>& b) {
         e.mapStart();
         if (! b.empty()) {
@@ -176,6 +271,9 @@ template <typename T> struct codec_trait
         e.mapEnd();
     }
 
+    /**
+     * Decodes into a given value.
+     */
     static void decode(Decoder& d, std::map<std::string, T>& s) {
         s.clear();
         for (size_t n = d.mapStart(); n != 0; n = d.mapNext()) {
@@ -190,11 +288,17 @@ template <typename T> struct codec_trait
     }
 };
 
+/**
+ * Generic encoder function that makes use of the codec_traits.
+ */
 template <typename T>
 void encode(Encoder& e, const T& t) {
     codec_traits<T>::encode(e, t);
 }
 
+/**
+ * Generic decoder function that makes use of the codec_traits.
+ */
 template <typename T>
 void decode(Decoder& d, T& t) {
     codec_traits<T>::decode(d, t);

Modified: avro/trunk/lang/c++/api/Stream.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Stream.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Stream.hh (original)
+++ avro/trunk/lang/c++/api/Stream.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -26,9 +26,22 @@
 #include "Exception.hh"
 
 namespace avro {
+
+/**
+ * A no-copy input stream.
+ */
 class InputStream : boost::noncopyable {
-public:
+protected:
+
+    /**
+     * An empty constuctor.
+     */
     InputStream() { }
+
+public:
+    /**
+     * Destructor.
+     */
     virtual ~InputStream() { }
 
     /**
@@ -59,9 +72,21 @@ public:
     virtual size_t byteCount() const = 0;
 };
 
+/**
+ * A no-copy output stream.
+ */
 class OutputStream : boost::noncopyable {
-public:
+protected:
+
+    /**
+     * An empty constuctor.
+     */
     OutputStream() { }
+public:
+
+    /**
+     * Destructor.
+     */
     virtual ~OutputStream() { }
 
     /**
@@ -131,13 +156,35 @@ std::auto_ptr<InputStream> fileInputStre
 
 /** A convenience class for reading from an InputStream */
 struct StreamReader {
+    /**
+     * The underlying input stream.
+     */
     InputStream* in_;
+
+    /**
+     * The next location to read from.
+     */
     const uint8_t* next_;
+
+    /**
+     * One past the last valid location.
+     */
     const uint8_t* end_;
 
+    /**
+     * Constructs an empty reader.
+     */
     StreamReader() : in_(0), next_(0), end_(0) { }
+
+    /**
+     * Constructs a reader with the given underlying stream.
+     */
     StreamReader(InputStream& in) : in_(0), next_(0), end_(0) { reset(in); }
 
+    /**
+     * Replaces the current input stream with the given one after backing up
+     * the original one if required.
+     */
     void reset(InputStream& is) {
         if (in_ != 0 && end_ != next_) {
             in_->backup(end_ - next_);
@@ -146,6 +193,10 @@ struct StreamReader {
         next_ = end_ = 0;
     }
 
+    /**
+     * Read just one byte from the underlying stream. If there are no
+     * more data, throws an exception.
+     */
     uint8_t read() {
         if (next_ == end_) {
             more();
@@ -153,6 +204,10 @@ struct StreamReader {
         return *next_++;
     }
 
+    /**
+     * Reads the given number of bytes from the underlying stream.
+     * If there are not that many bytes, throws an exception.
+     */
     void readBytes(uint8_t* b, size_t n) {
         while (n > 0) {
             if (next_ == end_) {
@@ -169,6 +224,10 @@ struct StreamReader {
         }
     }
 
+    /**
+     * Skips the given number of bytes. Of there are not so that many
+     * bytes, throws an exception.
+     */
     void skipBytes(size_t n) {
         if (n > static_cast<size_t>(end_ - next_)) {
             n -= end_ - next_;
@@ -179,6 +238,12 @@ struct StreamReader {
         }
     }
 
+    /**
+     * Get as many byes from the underlying stream as possible in a single
+     * chunk.
+     * \return true if some data could be obtained. False is no more
+     * data is available on the stream.
+     */
     bool fill() {
         size_t n = 0;
         while (in_->next(&next_, &n)) {
@@ -190,12 +255,18 @@ struct StreamReader {
         return false;
     }
 
+    /**
+     * Tries to get more data and if it cannot, throws an exception.
+     */
     void more() {
         if (! fill()) {
             throw Exception("EOF reached");
         }
     }
 
+    /**
+     * Returns true if and only if the end of stream is not reached.
+     */
     bool hasMore() {
         return (next_ == end_) ? fill() : true;
     }
@@ -205,13 +276,35 @@ struct StreamReader {
  * A convinience class to write data into an OutputStream.
  */
 struct StreamWriter {
+    /**
+     * The underlying output stream for this writer.
+     */
     OutputStream* out_;
+
+    /**
+     * The next location to write to.
+     */
     uint8_t* next_;
+    
+    /**
+     * One past the last location one can write to.
+     */
     uint8_t* end_;
 
+    /**
+     * Constructs a writer with no underlying stream.
+     */
     StreamWriter() : out_(0), next_(0), end_(0) { }
+
+    /**
+     * Constructs a new writer with the given underlying stream.
+     */
     StreamWriter(OutputStream& out) : out_(0), next_(0), end_(0) { reset(out); }
 
+    /**
+     * Replaces the current underlying stream with a new one.
+     * If required, it backs up unused bytes in the previous stream.
+     */
     void reset(OutputStream& os) {
         if (out_ != 0 && end_ != next_) {
             out_->backup(end_ - next_);
@@ -220,6 +313,9 @@ struct StreamWriter {
         next_ = end_;
     }
 
+    /**
+     * Writes a single byte.
+     */
     void write(uint8_t c) {
         if (next_ == end_) {
             more();
@@ -227,6 +323,9 @@ struct StreamWriter {
         *next_++ = c;
     }
 
+    /**
+     * Writes the specified number of bytes starting at \p b.
+     */
     void writeBytes(const uint8_t* b, size_t n) {
         while (n > 0) {
             if (next_ == end_) {
@@ -243,6 +342,21 @@ struct StreamWriter {
         }
     }
 
+    /**
+     * backs up upto the currently written data and flushes the
+     * underlying stream.
+     */
+    void flush() {
+        if (next_ != end_) {
+            out_->backup(end_ - next_);
+            next_ = end_;
+        }
+        out_->flush();
+    }
+
+    /**
+     * Gets more space to write to. Throws an exception it cannot.
+     */
     void more() {
         size_t n = 0;
         while (out_->next(&next_, &n)) {
@@ -254,13 +368,6 @@ struct StreamWriter {
         throw Exception("EOF reached");
     }
 
-    void flush() {
-        if (next_ != end_) {
-            out_->backup(end_ - next_);
-            next_ = end_;
-        }
-        out_->flush();
-    }
 };
 
 /**

Modified: avro/trunk/lang/c++/api/SymbolMap.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/SymbolMap.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/SymbolMap.hh (original)
+++ avro/trunk/lang/c++/api/SymbolMap.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Types.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Types.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Types.hh (original)
+++ avro/trunk/lang/c++/api/Types.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -23,57 +23,87 @@
 
 namespace avro {
 
+/**
+ * The "type" for the schema.
+ */
 enum Type {
 
-    AVRO_STRING,
-    AVRO_BYTES,
-    AVRO_INT,
-    AVRO_LONG,
-    AVRO_FLOAT,
-    AVRO_DOUBLE,
-    AVRO_BOOL,
-    AVRO_NULL,
-
-    AVRO_RECORD,
-    AVRO_ENUM,
-    AVRO_ARRAY,
-    AVRO_MAP,
-    AVRO_UNION,
-    AVRO_FIXED,
+    AVRO_STRING,    /*!< String */
+    AVRO_BYTES,     /*!< Sequence of variable length bytes data */
+    AVRO_INT,       /*!< 32-bit integer */
+    AVRO_LONG,      /*!< 64-bit integer */
+    AVRO_FLOAT,     /*!< Floating point number */
+    AVRO_DOUBLE,    /*!< Double precision floating point number */
+    AVRO_BOOL,      /*!< Boolean value */
+    AVRO_NULL,      /*!< Null */
+
+    AVRO_RECORD,    /*!< Record, a sequence of fields */
+    AVRO_ENUM,      /*!< Enumeration */
+    AVRO_ARRAY,     /*!< Homogeneous array of some specific type */
+    AVRO_MAP,       /*!< Homogeneous map from string to some specific type */
+    AVRO_UNION,     /*!< Union of one or more types */
+    AVRO_FIXED,     /*!< Fixed number of bytes */
 
-    AVRO_NUM_TYPES, // marker
+    AVRO_NUM_TYPES, /*!< Marker */
     
     // The following is a pseudo-type used in implementation
     
-    AVRO_SYMBOLIC = AVRO_NUM_TYPES,
-    AVRO_UNKNOWN  = -1
+    AVRO_SYMBOLIC = AVRO_NUM_TYPES, /*!< User internally to avoid circular references. */
+    AVRO_UNKNOWN  = -1 /*!< Used internally. */
 
 };
 
+/**
+ * Returns true if and only if the given type is a primitive.
+ * Primitive types are: string, bytes, int, long, float, double, boolean
+ * and null
+ */
 inline bool isPrimitive(Type t) {
     return (t >= AVRO_STRING) && (t < AVRO_RECORD);
 }
 
+/**
+ * Returns true if and only if the given type is a non primitive valid type.
+ * Primitive types are: string, bytes, int, long, float, double, boolean
+ * and null
+ */
 inline bool isCompound(Type t) {
     return (t>= AVRO_RECORD) && (t < AVRO_NUM_TYPES);
 }
 
+/**
+ * Returns true if and only if the given type is a valid avro type.
+ */
 inline bool isAvroType(Type t) {
     return (t >= AVRO_STRING) && (t < AVRO_NUM_TYPES);
 }
 
+/**
+ * Returns true if and only if the given type is within the valid range
+ * of enumeration.
+ */
 inline bool isAvroTypeOrPseudoType(Type t) {
     return (t >= AVRO_STRING) && (t <= AVRO_NUM_TYPES);
 }
 
-
+/**
+ * Converts the given type into a string. Useful for generating messages.
+ */
 const std::string& toString(Type type);
 
+/**
+ * Writes a string form of the given type into the given ostream.
+ */
 std::ostream &operator<< (std::ostream &os, avro::Type type);
 
 /// define a type to identify Null in template functions
 struct Null { };
 
+/**
+ * Writes schema for null \p null type to \p os.
+ * \param os The ostream to write to.
+ * \param null The value to be written.
+ */
 std::ostream& operator<< (std::ostream &os, const Null &null);
 
 } // namespace avro

Modified: avro/trunk/lang/c++/api/ValidSchema.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/ValidSchema.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/ValidSchema.hh (original)
+++ avro/trunk/lang/c++/api/ValidSchema.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Validator.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Validator.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Validator.hh (original)
+++ avro/trunk/lang/c++/api/Validator.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Writer.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Writer.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Writer.hh (original)
+++ avro/trunk/lang/c++/api/Writer.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/Zigzag.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/Zigzag.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/Zigzag.hh (original)
+++ avro/trunk/lang/c++/api/Zigzag.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/Buffer.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/Buffer.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/Buffer.hh (original)
+++ avro/trunk/lang/c++/api/buffer/Buffer.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/BufferPrint.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/BufferPrint.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/BufferPrint.hh (original)
+++ avro/trunk/lang/c++/api/buffer/BufferPrint.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/BufferReader.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/BufferReader.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/BufferReader.hh (original)
+++ avro/trunk/lang/c++/api/buffer/BufferReader.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/BufferStream.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/BufferStream.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/BufferStream.hh (original)
+++ avro/trunk/lang/c++/api/buffer/BufferStream.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/BufferStreambuf.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/BufferStreambuf.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/BufferStreambuf.hh (original)
+++ avro/trunk/lang/c++/api/buffer/BufferStreambuf.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/detail/BufferDetail.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/detail/BufferDetail.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/detail/BufferDetail.hh (original)
+++ avro/trunk/lang/c++/api/buffer/detail/BufferDetail.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/api/buffer/detail/BufferDetailIterator.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/api/buffer/detail/BufferDetailIterator.hh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/api/buffer/detail/BufferDetailIterator.hh (original)
+++ avro/trunk/lang/c++/api/buffer/detail/BufferDetailIterator.hh Mon Oct 17 07:14:12 2011
@@ -1,4 +1,4 @@
-/**
+/*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information

Modified: avro/trunk/lang/c++/build.sh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/build.sh?rev=1185027&r1=1185026&r2=1185027&view=diff
==============================================================================
--- avro/trunk/lang/c++/build.sh (original)
+++ avro/trunk/lang/c++/build.sh Mon Oct 17 07:14:12 2011
@@ -62,7 +62,7 @@ function do_dist() {
     rm -rf $BUILD_CPP/
     mkdir -p $BUILD_CPP
     cp -r api AUTHORS build.sh CMakeLists.txt ChangeLog \
-        COPYING impl jsonschemas NEWS parser README scripts test \
+        COPYING impl jsonschemas NEWS parser README scripts test examples \
         $BUILD_CPP
     find $BUILD_CPP -name '.svn' | xargs rm -rf
     cp ../../share/VERSION.txt $BUILD_CPP

Added: avro/trunk/lang/c++/examples/cpx.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/cpx.hh?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/cpx.hh (added)
+++ avro/trunk/lang/c++/examples/cpx.hh Mon Oct 17 07:14:12 2011
@@ -0,0 +1,49 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#ifndef CPX_HH_1278398428__H_
+#define CPX_HH_1278398428__H_
+
+
+#include "boost/any.hpp"
+#include "avro/Specific.hh"
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+
+namespace c {
+struct cpx {
+    double re;
+    double im;
+};
+
+}
+namespace avro {
+template<> struct codec_traits<c::cpx> {
+    static void encode(Encoder& e, const c::cpx& v) {
+        avro::encode(e, v.re);
+        avro::encode(e, v.im);
+    }
+    static void decode(Decoder& d, c::cpx& v) {
+        avro::decode(d, v.re);
+        avro::decode(d, v.im);
+    }
+};
+
+}
+#endif

Added: avro/trunk/lang/c++/examples/cpx.json
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/cpx.json?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/cpx.json (added)
+++ avro/trunk/lang/c++/examples/cpx.json Mon Oct 17 07:14:12 2011
@@ -0,0 +1,8 @@
+{
+    "type": "record", 
+    "name": "cpx",
+    "fields" : [
+        {"name": "re", "type": "double"},    
+        {"name": "im", "type" : "double"}
+    ]
+}

Added: avro/trunk/lang/c++/examples/custom.cc
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/custom.cc?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/custom.cc (added)
+++ avro/trunk/lang/c++/examples/custom.cc Mon Oct 17 07:14:12 2011
@@ -0,0 +1,41 @@
+#include <complex>
+
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+#include "avro/Specific.hh"
+
+namespace avro {
+template<typename T>
+struct codec_traits<std::complex<T> > {
+    static void encode(Encoder& e, const std::complex<T>& c) {
+        avro::encode(e, std::real(c));
+        avro::encode(e, std::imag(c));
+    }
+
+    static void decode(Decoder& d, std::complex<T>& c) {
+        T re, im;
+        avro::decode(d, re);
+        avro::decode(d, im);
+        c = std::complex<T>(re, im);
+    }
+};
+
+}
+int
+main()
+{
+    std::auto_ptr<avro::OutputStream> out = avro::memoryOutputStream();
+    avro::EncoderPtr e = avro::binaryEncoder();
+    e->init(*out);
+    std::complex<double> c1(1.0, 2.0);
+    avro::encode(*e, c1);
+
+    std::auto_ptr<avro::InputStream> in = avro::memoryInputStream(*out);
+    avro::DecoderPtr d = avro::binaryDecoder();
+    d->init(*in);
+
+    std::complex<double> c2;
+    avro::decode(*d, c2);
+    std::cout << '(' << std::real(c2) << ", " << std::imag(c2) << ')' << std::endl;
+    return 0;
+}

Added: avro/trunk/lang/c++/examples/datafile.cc
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/datafile.cc?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/datafile.cc (added)
+++ avro/trunk/lang/c++/examples/datafile.cc Mon Oct 17 07:14:12 2011
@@ -0,0 +1,44 @@
+#include <fstream>
+
+#include "cpx.hh"
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+#include "avro/ValidSchema.hh"
+#include "avro/Compiler.hh"
+#include "avro/DataFile.hh"
+
+
+avro::ValidSchema loadSchema(const char* filename)
+{
+    std::ifstream ifs(filename);
+    avro::ValidSchema result;
+    avro::compileJsonSchema(ifs, result);
+    return result;
+}
+
+int
+main()
+{
+    avro::ValidSchema cpxSchema = loadSchema("cpx.json");
+
+    {
+        avro::DataFileWriter<c::cpx> dfw("test.bin", cpxSchema);
+        c::cpx c1;
+        for (int i = 0; i < 100; i++) {
+            c1.re = i * 100;
+            c1.im = i + 100;
+            dfw.write(c1);
+        }
+        dfw.close();
+    }
+
+    {
+        avro::DataFileReader<c::cpx> dfr("test.bin", cpxSchema);
+        c::cpx c2;
+        while (dfr.read(c2)) {
+            std::cout << '(' << c2.re << ", " << c2.im << ')' << std::endl;
+        }
+    }
+    return 0;
+}
+

Added: avro/trunk/lang/c++/examples/generated.cc
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/generated.cc?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/generated.cc (added)
+++ avro/trunk/lang/c++/examples/generated.cc Mon Oct 17 07:14:12 2011
@@ -0,0 +1,26 @@
+#include "cpx.hh"
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+
+
+int
+main()
+{
+    std::auto_ptr<avro::OutputStream> out = avro::memoryOutputStream();
+    avro::EncoderPtr e = avro::binaryEncoder();
+    e->init(*out);
+    c::cpx c1;
+    c1.re = 1.0;
+    c1.im = 2.13;
+    avro::encode(*e, c1);
+
+    std::auto_ptr<avro::InputStream> in = avro::memoryInputStream(*out);
+    avro::DecoderPtr d = avro::binaryDecoder();
+    d->init(*in);
+
+    c::cpx c2;
+    avro::decode(*d, c2);
+    std::cout << '(' << c2.re << ", " << c2.im << ')' << std::endl;
+    return 0;
+}
+

Added: avro/trunk/lang/c++/examples/generic.cc
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/generic.cc?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/generic.cc (added)
+++ avro/trunk/lang/c++/examples/generic.cc Mon Oct 17 07:14:12 2011
@@ -0,0 +1,52 @@
+#include <fstream>
+#include <complex>
+
+#include "cpx.hh"
+
+#include "avro/Compiler.hh"
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+#include "avro/Specific.hh"
+#include "avro/Generic.hh"
+
+int
+main()
+{
+    std::ifstream ifs("cpx.json");
+
+    avro::ValidSchema cpxSchema;
+    avro::compileJsonSchema(ifs, cpxSchema);
+
+    std::auto_ptr<avro::OutputStream> out = avro::memoryOutputStream();
+    avro::EncoderPtr e = avro::binaryEncoder();
+    e->init(*out);
+    c::cpx c1;
+    c1.re = 100.23;
+    c1.im = 105.77;
+    avro::encode(*e, c1);
+
+    std::auto_ptr<avro::InputStream> in = avro::memoryInputStream(*out);
+    avro::DecoderPtr d = avro::binaryDecoder();
+    d->init(*in);
+
+    std::pair<avro::ValidSchema, avro::GenericDatum> p(cpxSchema,
+        avro::GenericDatum(cpxSchema.root()));
+    avro::decode(*d, p);
+    const avro::GenericDatum& datum = p.second;
+    std::cout << "Type: " << datum.type() << std::endl;
+    if (datum.type() == avro::AVRO_RECORD) {
+        const avro::GenericRecord& r = datum.value<avro::GenericRecord>();
+        std::cout << "Field-count: " << r.fieldCount() << std::endl;
+        if (r.fieldCount() == 2) {
+            const avro::GenericDatum& f0 = r.fieldAt(0);
+            if (f0.type() == avro::AVRO_DOUBLE) {
+                std::cout << "Real: " << f0.value<double>() << std::endl;
+            }
+            const avro::GenericDatum& f1 = r.fieldAt(1);
+            if (f1.type() == avro::AVRO_DOUBLE) {
+                std::cout << "Imaginary: " << f1.value<double>() << std::endl;
+            }
+        }
+    }
+    return 0;
+}

Added: avro/trunk/lang/c++/examples/imaginary.hh
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/imaginary.hh?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/imaginary.hh (added)
+++ avro/trunk/lang/c++/examples/imaginary.hh Mon Oct 17 07:14:12 2011
@@ -0,0 +1,46 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#ifndef IMAGINARY_HH_3460301992__H_
+#define IMAGINARY_HH_3460301992__H_
+
+
+#include "boost/any.hpp"
+#include "avro/Specific.hh"
+#include "avro/Encoder.hh"
+#include "avro/Decoder.hh"
+
+namespace i {
+struct cpx {
+    double im;
+};
+
+}
+namespace avro {
+template<> struct codec_traits<i::cpx> {
+    static void encode(Encoder& e, const i::cpx& v) {
+        avro::encode(e, v.im);
+    }
+    static void decode(Decoder& d, i::cpx& v) {
+        avro::decode(d, v.im);
+    }
+};
+
+}
+#endif

Added: avro/trunk/lang/c++/examples/imaginary.json
URL: http://svn.apache.org/viewvc/avro/trunk/lang/c%2B%2B/examples/imaginary.json?rev=1185027&view=auto
==============================================================================
--- avro/trunk/lang/c++/examples/imaginary.json (added)
+++ avro/trunk/lang/c++/examples/imaginary.json Mon Oct 17 07:14:12 2011
@@ -0,0 +1,7 @@
+{
+    "type": "record", 
+    "name": "cpx",
+    "fields" : [
+        {"name": "im", "type" : "double"}
+    ]
+}



Mime
View raw message