Avro RPC 之 Protocol 定义和代码生成

摘自http://avro.apache.org/docs/current/spec.html#Protocol+Declaration，1.7.6版

Protocol Declaration

Avro protocols describe RPC interfaces. Like schemas, they are defined with JSON text.

A protocol is a JSON object with the following attributes:

• protocol, a string, the name of the protocol (required);
• namespace, an optional string that qualifies the name;
• doc, an optional string describing this protocol;
• types, an optional list of definitions of named types (records, enums, fixed and errors). An error definition is just like a record definition except it uses "error" instead of "record". Note that forward references to named types are not permitted.
• messages, an optional JSON object whose keys are message names and whose values are objects whose attributes are described below. No two messages may have the same name.

The name and namespace qualification rules defined for schema objects apply to protocols as well.

Avro protocol 描述了RPC接口，和schema一样，用JSON定义。

一个protocol是一个JSON对象，有以下的属性：

• protocol，必需，这个protocol的名字
• namespace, 可选，用来qualify protocol的名字
• doc, 可选，描述这个protocol
• types, 可选，定义named types的列表（records, enums, fixed, errors）。error的定义和record一样，除了它使用error，而不是record. 注意named type不能进行forward reference. (注：就是定义了一些类型，然后给每个类型起个名字)
• messages, 可选，是一个JSON对象。它的key是message name， values是JSON 对象， 下边会讲这个JSON对象的属性。message不能有相同的名字。

用于schema object的命名规则和namespace qualification规则同样适用于protocol

Messages

A message has attributes:

• a doc, an optional description of the message,
• a request, a list of named, typed parameter schemas (this has the same form as the fields of a record declaration);
• a response schema;
• an optional union of declared error schemas. The effective union has "string" prepended to the declared union, to permit transmission of undeclared "system" errors. For example, if the declared error union is ["AccessError"], then the effective union is ["string", "AccessError"]. When no errors are declared, the effective error union is ["string"]. Errors are serialized using the effective union; however, a protocol's JSON declaration contains only the declared union.
• an optional one-way boolean parameter.

A request parameter list is processed equivalently to an anonymous record. Since record field lists may vary between reader and writer, request parameters may also differ between the caller and responder, and such differences are resolved in the same manner as record field differences.

The one-way parameter may only be true when the response type is "null" and no errors are listed.

 message有以下属性：

• doc, 可选，对消息的说明
• request,  一个参数列表，其中的参数拥有名字和类型(和record中的field的定义格式一样)  。（注：即需要说明参数的名字和类型）

   "request": [{"name": "greeting", "type": "Greeting" }]

• response的schema 

  "response": "Greeting",

• error, 用一个declared union来描述，可选。之所以叫"delcared" union，是因为实际上隐式地附加了一个String到这个union中，这样没有声明的"system error" 也可以传输了。例如，declared error union是["AccessError"]，effective union就是["String", "AccessError"]。如果没有声明error， effective error union就是["string"]。错误 被用effective union序列化。但是这个protocol的JSON形式的定义里就只用写declared union了。
• one-way 布尔类型参数，可选

请求的参数列表就和匿名record一样处理。因为record field列表在reader和writer间可以不同，request 参数在caller和responder之间也可以不同，这样的不同和record field不同采用同样的方式处理。

当response 类型是null，并且没有列出error时，one-way parameter只能是true.

Sample Protocol

For example, one may define a simple HelloWorld protocol with:

{
  "namespace": "com.acme",
  "protocol": "HelloWorld",
  "doc": "Protocol Greetings",

  "types": [
    {"name": "Greeting", "type": "record", "fields": [
      {"name": "message", "type": "string"}]},
    {"name": "Curse", "type": "error", "fields": [
      {"name": "message", "type": "string"}]}
  ],

  "messages": {
    "hello": {
      "doc": "Say hello.",
      "request": [{"name": "greeting", "type": "Greeting" }],
      "response": "Greeting",
      "errors": ["Curse"]
    }
  }
}
        

 总结：搞了这么多，这个protocol的定义实际上就是定义了一些用于RPC的方法，不过在定义方法时要声明方法的参数名、参数类型、返回类型、异常啥的。这些方法要定义于一个接口，所以还要说明这个接口的名字（在上边的例子中是HelloWorld）.

生成对应的java代码

把上边的protocol写上一个HelloWorld.avpr中，然后执行java -jar avro-tools- 1.7.6.jar compile protocol HelloWorld.avpr /target/java 就会得到三个文件

• Curse.java. public class Curse extends org.apache.avro.specific.SpecificExceptionBase implements org.apache.avro.specific.SpecificRecord 这个就是上边定义的error，这个类是一个异常。
• Greeting.java.public class Greeting extends org.apache.avro.specific.SpecificRecordBase implements org.apache.avro.specific.SpecificRecord 这个就是参数类型，被生成为一个类，它是一个record类型。
• HelloWorld.java 

/**
 * Autogenerated by Avro
 * 
 * DO NOT EDIT DIRECTLY
 */
package com.acme;

@SuppressWarnings("all")
/** Protocol Greetings */
@org.apache.avro.specific.AvroGenerated
public interface HelloWorld {
  public static final org.apache.avro.Protocol PROTOCOL = org.apache.avro.Protocol.parse("{"protocol":"HelloWorld","namespace":"com.acme","doc":"Protocol Greetings","types":[{"type":"record","name":"Greeting","fields":[{"name":"message","type":"string"}]},{"type":"error","name":"Curse","fields":[{"name":"message","type":"string"}]}],"messages":{"hello":{"doc":"Say hello.","request":[{"name":"greeting","type":"Greeting"}],"response":"Greeting","errors":["Curse"]}}}");
  /** Say hello. */
  com.acme.Greeting hello(com.acme.Greeting greeting) throws org.apache.avro.AvroRemoteException, com.acme.Curse;

  @SuppressWarnings("all")
  /** Protocol Greetings */
  public interface Callback extends HelloWorld {
    public static final org.apache.avro.Protocol PROTOCOL = com.acme.HelloWorld.PROTOCOL;
    /** Say hello. */
    void hello(com.acme.Greeting greeting, org.apache.avro.ipc.Callback<com.acme.Greeting> callback) throws java.io.IOException;
  }
}

　　它是一个接口，定义了一个叫hello的方法，就是前边给message起的名字。它的参数和返回类型、抛出的异常都符合对应procotol的声明。doc被转换为了对应于方法和类的注释。