You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by cu...@apache.org on 2011/09/20 19:55:22 UTC
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...
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