标签：style blog http java 使用 os io strong
这篇入门教程是基于Java语言的，这篇文章我们将会：
这篇文章仅是入门手册，如果想深入学习及了解，可以参看： Protocol Buffer Language Guide, Java API Reference, Java Generated Code Guide, 以及Encoding Reference。
接下来用“通讯簿”这样一个非常简单的应用来举例。该应用能够写入并读取“联系人”信息，每个联系人由name，ID，email address以及contact photo number组成。这些信息的最终存储在文件中。
如何序列化并检索这样的结构化数据呢？有以下解决方案：
Protocol Buffers可以灵活，高效且自动化的解决该问题，只需要：
该生成类提供组成PB数据字段的getter和setter方法，甚至考虑了如何高效的读写PB数据。更厉害的是，PB友好的支持字段拓展，拓展后的代码，依然能够正确的读取原来格式编码的数据。
首先需要创建一个.proto文件。非常简单，每一个需要序列化的数据结构，编码一个PB message，然后为message中的字段指明一个名字和类型即可。该“通讯簿”的.proto 文件addressbook.proto定义如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
package tutorial; option java_package = "com.example.tutorial"; option java_outer_classname = "AddressBookProtos"; message Person { required string name = 1; required int32 id = 2; optional string email = 3; enum PhoneType { MOBILE = 0; HOME = 1; WORK = 2; } message PhoneNumber { required string number = 1; optional PhoneType type = 2 [default = HOME]; } repeated PhoneNumber phone = 4; } message AddressBook { repeated Person person = 1; } |
可以看到，语法非常类似Java或者C++，接下来，我们一条一条来过一遍每句话的含义：
message的没一个字段，都要用如下的三个修饰符(modifier)来声明：
Notice：应该格外小心定义Required字段。当因为某原因要把Required字段改为Optional字段是，会有问题，老版本读取器会认为消息中没有该字段不完整，可能会拒绝或者丢弃该字段(Google文档是这么说的，但是我试了一下，将required的改为optional的，再用原来required时候的解析代码去读，如果字段赋值的话，并不会出错，但是如果字段未赋值，会报这样错误：Exception in thread "main" com.google.protobuf.InvalidProtocolBufferException: Message missing required fields:fieldname)。在设计时，尽量将这种验证放在应用程序端的完成。Google的一些工程师对此也很困惑，他们觉得，required类型坏处大于好处，应该尽量仅适用optional或者repeated的。但也并不是所有的人都这么想。
如果想深入学习.proto文件书写，可以参考Protocol Buffer Language Guide。但是不要妄想会有类似于类继承这样的机制，Protocol Buffers不做这个...
定义好.proto文件后，接下来，就是使用该文件，运行PB的编译器protoc，编译.proto文件，生成相关类，可以使用这些类读写“通讯簿”没得message。接下来我们要做：
|
1
2
3
|
protoc -I=$SRC_DIR --java_out=$DST_DIR $SRC_DIR/addressbook.proto #for example protoc -I=G:\workspace\protobuf\message --java_out=G:\workspace\protobuf\src\main\java G:\workspace\protobuf\messages\addressbook.proto |
Notice：此处运行完毕后，查看生成的代码，很有可能会出现一些类没有定义等错误，例如：com.google cannot be resolved to a type等。这是因为项目中缺少protocol buffers的相应library。在Protocol Buffers的源码包里，你会发现java/src/main/java，将这下边的文件拷贝到你的项目，大概可以解决问题。我只能说大概，因为当时我在弄得时候，也是刚学，各种出错，比较恶心。有一个简单的方法，呵呵，对于懒汉来说。创建一个maven的java项目，在pom.xml中，添加Protocol Buffers的依赖即可解决所有问题~在pom.xml中添加如下依赖(注意版本)：
<dependency> <groupId>com.google.protobuf</groupId> <artifactId>protobuf-java</artifactId> <version>2.5.0</version> </dependency>
接下来看一下PB编译器创建了那些类以及方法。首先会发现一个.java文件，其内部定义了一个AddressBookProtos类，即我们在addressbook.proto文件java_outer_classname 指定的。该类内部有一系列内部类，对应分别是我们在addressbook.proto中定义的message。每个类内部都有相应的Builder类，我们可以用它创建类的实例。生成的类及类内部的Builder类，均自动生成了获取message中字段的方法，不同的是，生成的类仅有getter方法，而生成类内部的Builder既有getter方法，又有setter方法。本例中Person类，其仅有getter方法，如图所示：
但是Person.Builder类，既有getter方法，又有setter方法，如图：
从上边两张图可以看到：
对于repeated字段：
从图上看：
注意到一点：所有的这些方法均命名均符合驼峰规则，即使在.proto文件中是小写的。PB compiler生成的方法及字段等都是按照驼峰规则来产生，以符合基本的Java规范，当然，其他语言也尽量如此。所以，在proto文件中，命名最好使用用“_”来分割不同小写的单词。
从代码中可以发现，还产生了一个枚举：PhoneType，该枚举位于Person类内部：
public enum PhoneType
implements com.google.protobuf.ProtocolMessageEnum {
/**
* <code>MOBILE = 0;</code>
*/
MOBILE(0, 0),
/**
* <code>HOME = 1;</code>
*/
HOME(1, 1),
/**
* <code>WORK = 2;</code>
*/
WORK(2, 2),
;
...
}
除此之外，如我们所预料，还有一个Person.PhoneNumber内部类，嵌套在Person类中，可以自行看一下生成代码，不再粘贴。
由PB compiler生成的消息类是不可变的。一旦一个消息对象构建出来，他就不再能够修改，就像java中的String一样。在构建一个message之前，首先要构建一个builder，然后使用builder的setter或者add()等方法为所需字段赋值，之后调用builder对象的build方法。
在使用中会发现，这些构造message对象的builder的方法，都又会返回一个新的builder，事实上，该builder跟调用这个方法的builder是同一方法。这样做的目的，仅是为了方便而已，我们可以把所有的setter写在一行内。
如下构造一个Person实例：
Person john = Person
.newBuilder()
.setId(1)
.setName("john")
.setEmail("john@youku.com")
.addPhone(
PhoneNumber
.newBuilder()
.setNumber("1861xxxxxxx")
.setType(PhoneType.WORK)
.build()
).build();
每一个消息类及Builder类，基本都包含一些公用方法，用来检查和维护这个message，包括：
对于每一个PB类，均提供了读写二进制数据的方法：
这里仅列出了几个解析及序列化方法，完整列表，可以参见：Message API reference
接下来使用这些生成的PB类，初始化一些联系人，并将其写入一个文件中。
下面的程序首先从一个文件中读取一个通讯簿(AddressBook)，然后添加一个新的联系人，再将新的通讯簿写回到文件。
package com.example.tutorial;
import com.example.tutorial.AddressBookProtos.AddressBook;
import com.example.tutorial.AddressBookProtos.Person;
import java.io.BufferedReader;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.PrintStream;
class AddPerson {
// This function fills in a Person message based on user input.
static Person PromptForAddress(BufferedReader stdin, PrintStream stdout)
throws IOException {
Person.Builder person = Person.newBuilder();
stdout.print("Enter person ID: ");
person.setId(Integer.valueOf(stdin.readLine()));
stdout.print("Enter name: ");
person.setName(stdin.readLine());
stdout.print("Enter email address (blank for none): ");
String email = stdin.readLine();
if (email.length() > 0) {
person.setEmail(email);
}
while (true) {
stdout.print("Enter a phone number (or leave blank to finish): ");
String number = stdin.readLine();
if (number.length() == 0) {
break;
}
Person.PhoneNumber.Builder phoneNumber = Person.PhoneNumber
.newBuilder().setNumber(number);
stdout.print("Is this a mobile, home, or work phone? ");
String type = stdin.readLine();
if (type.equals("mobile")) {
phoneNumber.setType(Person.PhoneType.MOBILE);
} else if (type.equals("home")) {
phoneNumber.setType(Person.PhoneType.HOME);
} else if (type.equals("work")) {
phoneNumber.setType(Person.PhoneType.WORK);
} else {
stdout.println("Unknown phone type. Using default.");
}
person.addPhone(phoneNumber);
}
return person.build();
}
// Main function: Reads the entire address book from a file,
// adds one person based on user input, then writes it back out to the same
// file.
public static void main(String[] args) throws Exception {
if (args.length != 1) {
System.err.println("Usage: AddPerson ADDRESS_BOOK_FILE");
System.exit(-1);
}
AddressBook.Builder addressBook = AddressBook.newBuilder();
// Read the existing address book.
try {
addressBook.mergeFrom(new FileInputStream(args[0]));
} catch (FileNotFoundException e) {
System.out.println(args[0]
+ ": File not found. Creating a new file.");
}
// Add an address.
addressBook.addPerson(PromptForAddress(new BufferedReader(
new InputStreamReader(System.in)), System.out));
// Write the new address book back to disk.
FileOutputStream output = new FileOutputStream(args[0]);
addressBook.build().writeTo(output);
output.close();
}
}
运行第六部分程序，写入几个联系人到文件中，接下来，我们就要读取联系人。程序入下：
package com.example.tutorial;
import java.io.FileInputStream;
import com.example.tutorial.AddressBookProtos.AddressBook;
import com.example.tutorial.AddressBookProtos.Person;
class ListPeople {
// Iterates though all people in the AddressBook and prints info about them.
static void Print(AddressBook addressBook) {
for (Person person: addressBook.getPersonList()) {
System.out.println("Person ID: " + person.getId());
System.out.println(" Name: " + person.getName());
if (person.hasEmail()) {
System.out.println(" E-mail address: " + person.getEmail());
}
for (Person.PhoneNumber phoneNumber : person.getPhoneList()) {
switch (phoneNumber.getType()) {
case MOBILE:
System.out.print(" Mobile phone #: ");
break;
case HOME:
System.out.print(" Home phone #: ");
break;
case WORK:
System.out.print(" Work phone #: ");
break;
}
System.out.println(phoneNumber.getNumber());
}
}
}
// Main function: Reads the entire address book from a file and prints all
// the information inside.
public static void main(String[] args) throws Exception {
if (args.length != 1) {
System.err.println("Usage: ListPeople ADDRESS_BOOK_FILE");
System.exit(-1);
}
// Read the existing address book.
AddressBook addressBook =
AddressBook.parseFrom(new FileInputStream(args[0]));
Print(addressBook);
}
}
至此我们已经可以使用生成类写入和读取PB message。
当产品发布后，迟早有一天我们需要改善我们的PB定义。如果要做到新的PB能够向后兼容，同时老的PB又能够向前兼容，我们必须遵守如下规则：
如果违反了这些规则，会有一些相应的异常，可参见some exceptions，但是这些异常，很少很少会被用到。
遵守这些规则，老的代码可以正确的读取新的message，但是会忽略新的字段；对于删掉的optional的字段，老代码会使用他们的默认值；对于删除的repeated字段，则把他们置为空。
新的代码也将能够透明的读取老的messages。但是必须注意，新的optional字段在老的message中是不存在的，必须显式的使用has_方法来判断其是否设置了，或者在.proto 文件中以[default = value]形式提供默认值。如果没有指定默认值的话，会按照类型默认值赋值。对于string类型，默认值是空字符串。对于bool来说，默认值是false。对于数字类型，默认值是0。
Protocol Buffers的应用远远不止简单的存取以及序列化。如果想了解更多用法，可以去研究Java API reference。
Protocol Message Class提供了一个重要特性：反射。不需要再写任何特殊的message类型就可以遍历一条message的所有字段以及操作字段的值。反射的一个非常重要的应用是可以将PBmessage与其他的编码语言进行转化，例如与XML或者JSON之间。
反射另外一个更加高级的应用应该是两个同一类型message的之间的不同，或者开发一种可以成为“Protocol Buffers 正则表达式”的应用，使用它，可以编写符合一定消息内容的表达式。
除此之外，开动脑筋，你会发现，Protocol Buffers能解决远远超过你刚开始对他的期待。
译自:https://developers.google.com/protocol-buffers/docs/javatutorial
说实话，翻译下来整个文章非常辛苦，而且都要敲代码去亲自试验能否通过，所以如果您想转载，非常欢迎，但请注明出处，也算是对俺辛苦的尊重~
Google Protocol Buffers 入门,布布扣,bubuko.com
标签：style blog http java 使用 os io strong
原文地址：http://www.cnblogs.com/For-her/p/3923964.html
