avro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cutt...@apache.org
Subject svn commit: r1173278 - in /avro/trunk: ./ lang/java/avro/src/main/java/org/apache/avro/ lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/ lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/ lang/java/compiler/src/test/idl...
Date Tue, 20 Sep 2011 17:55:22 GMT
Author: cutting
Date: Tue Sep 20 17:55:21 2011
New Revision: 1173278

URL: http://svn.apache.org/viewvc?rev=1173278&view=rev
Log:
AVRO-866. Java: Add support in IDL for documentation in protocols and messages.  Contributed
by George Fletcher.

Modified:
    avro/trunk/CHANGES.txt
    avro/trunk/lang/java/avro/src/main/java/org/apache/avro/Protocol.java
    avro/trunk/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java
    avro/trunk/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
    avro/trunk/lang/java/compiler/src/test/idl/input/simple.avdl
    avro/trunk/lang/java/compiler/src/test/idl/output/baseball.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/import.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/interop.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/mr_events.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/namespaces.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/reservedwords.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/simple.avpr
    avro/trunk/lang/java/compiler/src/test/idl/output/unicode.avpr
    avro/trunk/lang/java/compiler/src/test/java/org/apache/avro/compiler/idl/TestIdl.java
    avro/trunk/share/schemas/org/apache/avro/ipc/trace/avroTrace.avdl

Modified: avro/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/avro/trunk/CHANGES.txt?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/CHANGES.txt (original)
+++ avro/trunk/CHANGES.txt Tue Sep 20 17:55:21 2011
@@ -57,6 +57,9 @@ Avro 1.6.0 (unreleased)
     AVRO-858. Python: Add --fields option to 'avro cat' command.
     (Miki Tebeka via cutting)
 
+    AVRO-866. Java: Add support in IDL for documentation in protocols
+    and messages.  (George Fletcher via cutting)
+
   BUG FIXES
 
     AVRO-824. Java: Fix usage message of BinaryFragmentToJsonTool.

Modified: avro/trunk/lang/java/avro/src/main/java/org/apache/avro/Protocol.java
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/avro/src/main/java/org/apache/avro/Protocol.java?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/avro/src/main/java/org/apache/avro/Protocol.java (original)
+++ avro/trunk/lang/java/avro/src/main/java/org/apache/avro/Protocol.java Tue Sep 20 17:55:21
2011
@@ -99,6 +99,8 @@ public class Protocol {
     void toJson(JsonGenerator gen) throws IOException {
       gen.writeStartObject();
 
+      if (doc != null) gen.writeStringField("doc", doc);
+
       gen.writeFieldName("request");
       request.fieldsToJson(types, gen);
 
@@ -190,10 +192,14 @@ public class Protocol {
 
   private Protocol() {}
 
-  public Protocol(String name, String namespace) {
+  public Protocol(String name, String doc, String namespace) {
     this.name = name;
+    this.doc = doc;
     this.namespace = namespace;
   }
+  public Protocol(String name, String namespace) {
+    this(name, null, namespace);
+  }
 
   /** The name of this protocol. */
   public String getName() { return name; }
@@ -271,6 +277,8 @@ public class Protocol {
     gen.writeStartObject();
     gen.writeStringField("protocol", name);
     gen.writeStringField("namespace", namespace);
+
+    if (doc != null) gen.writeStringField("doc", doc);
     
     gen.writeArrayFieldStart("types");
     Schema.Names resolved = new Schema.Names(namespace);
@@ -379,6 +387,8 @@ public class Protocol {
   }
 
   private Message parseMessage(String messageName, JsonNode json) {
+    String doc = parseDocNode(json);
+
     JsonNode requestNode = json.get("request");
     if (requestNode == null || !requestNode.isArray())
       throw new SchemaParseException("No request specified: "+json);
@@ -437,7 +447,7 @@ public class Protocol {
         errs.add(schema);
       }
     }
-    String doc = parseDocNode(json);
+
     return new TwoWayMessage(messageName, doc, request, response,
                              Schema.createUnion(errs));
   }

Modified: avro/trunk/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java
(original)
+++ avro/trunk/lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java
Tue Sep 20 17:55:21 2011
@@ -368,9 +368,9 @@ public class SpecificCompiler {
     }
   }
 
-  /** Utility for template use.  Escapes quotes in java strings. */
+  /** Utility for template use.  Escapes quotes and backslashes. */
   public static String javaEscape(Object o) {
-    return o.toString().replace("\"", "\\\"");
+      return o.toString().replace("\\","\\\\").replace("\"", "\\\"");
   }
 
   /** Utility for template use.  Escapes comment end with HTML entities. */

Modified: avro/trunk/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj (original)
+++ avro/trunk/lang/java/compiler/src/main/javacc/org/apache/avro/compiler/idl/idl.jj Tue
Sep 20 17:55:21 2011
@@ -1046,8 +1046,7 @@ Protocol ProtocolDeclaration():
  "protocol"
    name = Identifier()
  {
-   getDoc();                                      // consume doc
-   p = new Protocol(name, namespace);
+   p = new Protocol(name, getDoc(), namespace);
  }
  ProtocolBody(p)
  {
@@ -1280,8 +1279,18 @@ void VariableDeclarator(Schema type, Lis
 }
 
 
+String MessageDocumentation():
+{}
+{
+   // Don't parse anything, just return the doc string
+   {
+       return getDoc();
+   }
+}
+
 Message MessageDeclaration(Protocol p):
 {
+  String msgDoc;
   String name;
   Schema request;
   Schema response;
@@ -1290,6 +1299,7 @@ Message MessageDeclaration(Protocol p):
   errorSchemata.add(Protocol.SYSTEM_ERROR);
 }
 {
+  msgDoc = MessageDocumentation()
   response = ResultType()
   name = Identifier()
   request = FormalParameters()
@@ -1300,8 +1310,8 @@ Message MessageDeclaration(Protocol p):
     if (oneWay && response.getType() != Type.NULL)
       throw error("One-way message'"+name+"' must return void", token);
     return oneWay
-    ? p.createMessage(name, null, request)
-    : p.createMessage(name, null, request, response, errors);
+    ? p.createMessage(name, msgDoc, request)
+    : p.createMessage(name, msgDoc, request, response, errors);
     
   }
 }

Modified: avro/trunk/lang/java/compiler/src/test/idl/input/simple.avdl
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/input/simple.avdl?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/input/simple.avdl (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/input/simple.avdl Tue Sep 20 17:55:21 2011
@@ -48,8 +48,10 @@ protocol Simple {
     string message;
   }
 
+  /** method 'hello' takes @parameter 'greeting' */
   string hello(string greeting);
   TestRecord echo(TestRecord `record` = {"name": "bar"});
+  /** method 'add' takes @parameter 'arg1' @parameter 'arg2' */
   int add(int arg1, int arg2 = 0);
   bytes echoBytes(bytes data);
   void `error`() throws TestError;

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/baseball.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/baseball.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/baseball.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/baseball.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Baseball",
   "namespace" : "avro.examples.baseball",
+  "doc" : "* Licensed to the Apache Software Foundation (ASF) under one\n * or more contributor
license agreements.  See the NOTICE file\n * distributed with this work for additional information\n
* regarding copyright ownership.  The ASF licenses this file\n * to you under the Apache License,
Version 2.0 (the\n * \"License\"); you may not use this file except in compliance\n * with
the License.  You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n
*\n * Unless required by applicable law or agreed to in writing, software\n * distributed
under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.\n * See the License for the specific language governing
permissions and\n * limitations under the License.",
   "types" : [ {
     "type" : "enum",
     "name" : "Position",

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/import.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/import.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/import.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/import.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Import",
   "namespace" : "org.foo",
+  "doc" : "* Licensed to the Apache Software Foundation (ASF) under one\n * or more contributor
license agreements.  See the NOTICE file\n * distributed with this work for additional information\n
* regarding copyright ownership.  The ASF licenses this file\n * to you under the Apache License,
Version 2.0 (the\n * \"License\"); you may not use this file except in compliance\n * with
the License.  You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n
*\n * Unless required by applicable law or agreed to in writing, software\n * distributed
under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.\n * See the License for the specific language governing
permissions and\n * limitations under the License.",
   "types" : [ {
     "type" : "record",
     "name" : "Foo",

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/interop.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/interop.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/interop.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/interop.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "InteropProtocol",
   "namespace" : "org.apache.avro",
+  "doc" : "* Licensed to the Apache Software Foundation (ASF) under one\n * or more contributor
license agreements.  See the NOTICE file\n * distributed with this work for additional information\n
* regarding copyright ownership.  The ASF licenses this file\n * to you under the Apache License,
Version 2.0 (the\n * \"License\"); you may not use this file except in compliance\n * with
the License.  You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n
*\n * Unless required by applicable law or agreed to in writing, software\n * distributed
under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.\n * See the License for the specific language governing
permissions and\n * limitations under the License.",
   "types" : [ {
     "type" : "record",
     "name" : "Foo",

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/mr_events.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/mr_events.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/mr_events.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/mr_events.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Events",
   "namespace" : "org.apache.hadoop.mapreduce.jobhistory",
+  "doc" : "* Genavro format for a particular protocol found in Hadoop MapReduce.\n * Used
as a test case/example to show that we can express real-world stuff more\n * succinctly.",
   "types" : [ {
     "type" : "record",
     "name" : "JhCounter",

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/namespaces.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/namespaces.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/namespaces.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/namespaces.avpr Tue Sep 20 17:55:21
2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "TestNamespace",
   "namespace" : "avro.test.protocol",
+  "doc" : "* Licensed to the Apache Software Foundation (ASF) under one\n * or more contributor
license agreements.  See the NOTICE file\n * distributed with this work for additional information\n
* regarding copyright ownership.  The ASF licenses this file\n * to you under the Apache License,
Version 2.0 (the\n * \"License\"); you may not use this file except in compliance\n * with
the License.  You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n
*\n * Unless required by applicable law or agreed to in writing, software\n * distributed
under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.\n * See the License for the specific language governing
permissions and\n * limitations under the License.",
   "types" : [ {
     "type" : "fixed",
     "name" : "FixedInOtherNamespace",

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/reservedwords.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/reservedwords.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/reservedwords.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/reservedwords.avpr Tue Sep 20 17:55:21
2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Foo",
   "namespace" : null,
+  "doc" : "* Licensed to the Apache Software Foundation (ASF) under one\n * or more contributor
license agreements.  See the NOTICE file\n * distributed with this work for additional information\n
* regarding copyright ownership.  The ASF licenses this file\n * to you under the Apache License,
Version 2.0 (the\n * \"License\"); you may not use this file except in compliance\n * with
the License.  You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n
*\n * Unless required by applicable law or agreed to in writing, software\n * distributed
under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, either express or implied.\n * See the License for the specific language governing
permissions and\n * limitations under the License.",
   "types" : [ ],
   "messages" : {
     "error" : {

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/simple.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/simple.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/simple.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/simple.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Simple",
   "namespace" : "org.apache.avro.test",
+  "doc" : "* A simple test case.",
   "types" : [ {
     "type" : "enum",
     "name" : "Kind",
@@ -45,6 +46,7 @@
   } ],
   "messages" : {
     "hello" : {
+      "doc" : "method 'hello' takes @parameter 'greeting'",
       "request" : [ {
         "name" : "greeting",
         "type" : "string"
@@ -62,6 +64,7 @@
       "response" : "TestRecord"
     },
     "add" : {
+      "doc" : "method 'add' takes @parameter 'arg1' @parameter 'arg2'",
       "request" : [ {
         "name" : "arg1",
         "type" : "int"

Modified: avro/trunk/lang/java/compiler/src/test/idl/output/unicode.avpr
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/idl/output/unicode.avpr?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/idl/output/unicode.avpr (original)
+++ avro/trunk/lang/java/compiler/src/test/idl/output/unicode.avpr Tue Sep 20 17:55:21 2011
@@ -1,6 +1,7 @@
 {
   "protocol" : "Протоколы",
   "namespace" : null,
+  "doc" : "* This is a test that UTF8 functions correctly.\n* このテストでは、UTF
- 8で正しく機能している。\n* 这是一个测试,UTF
- 8的正常运行。",
   "types" : [ {
     "type" : "record",
     "name" : "Структура",

Modified: avro/trunk/lang/java/compiler/src/test/java/org/apache/avro/compiler/idl/TestIdl.java
URL: http://svn.apache.org/viewvc/avro/trunk/lang/java/compiler/src/test/java/org/apache/avro/compiler/idl/TestIdl.java?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/lang/java/compiler/src/test/java/org/apache/avro/compiler/idl/TestIdl.java
(original)
+++ avro/trunk/lang/java/compiler/src/test/java/org/apache/avro/compiler/idl/TestIdl.java
Tue Sep 20 17:55:21 2011
@@ -90,6 +90,7 @@ public class TestIdl {
         passed++;
       } catch (Exception e) {
         failed++;
+        System.err.println("Failed: " + t.testName());
         e.printStackTrace(System.err);
       }
     }
@@ -126,6 +127,10 @@ public class TestIdl {
       return p.toString(true);
     }
 
+    public String testName() {
+        return this.in.getName();
+    }
+
     public void run() throws Exception {
       String output = generate();
       String slurped = slurp(expectedOut);

Modified: avro/trunk/share/schemas/org/apache/avro/ipc/trace/avroTrace.avdl
URL: http://svn.apache.org/viewvc/avro/trunk/share/schemas/org/apache/avro/ipc/trace/avroTrace.avdl?rev=1173278&r1=1173277&r2=1173278&view=diff
==============================================================================
--- avro/trunk/share/schemas/org/apache/avro/ipc/trace/avroTrace.avdl (original)
+++ avro/trunk/share/schemas/org/apache/avro/ipc/trace/avroTrace.avdl Tue Sep 20 17:55:21
2011
@@ -36,6 +36,10 @@ protocol AvroTrace {
     union { SpanEvent, string} event;
   }
 
+  /**
+   * An individual span is the basic unit of testing.
+   * The record is used by both \"client\" and \"server\".
+   */
   record Span {
     ID  traceID;  // ID shared by all Spans in a given trace
     ID spanID;    // Random ID for this Span



Mime
View raw message