消息

注:内容翻译自官网文档 Messages

给出一个简单的消息定义:

  1. message Foo {}

protocol buffer 编译器生成名为 Foo 的类,实现 Message 接口。这个类被定义为 final, 不容许任何子类。Foo 继承自 GeneratedMessage, 但是这个可以认为是实现细节。默认, Foo 用为实现最大速度的特别版本来覆盖很多 GeneratedMessage 的方法。不过,如果 .proto 文件包含这行:

  1. option optimize_for = CODE_SIZE;

则 Foo 将只覆盖功能必要方法的最小集合,而其他方法依赖 GeneratedMessage 的基于反射的实现。这显著的降低了生成代码的大小,但是也降低了性能。再不然,如果 .proto 文件包含:

  1. option optimize_for = LITE_RUNTIME;

那么 Foo 将包含所有方法的快速实现,但是将实现 MessageLite 接口,MessageLite 接口只包含 Message 的方法子集。尤其,它不支持描述符和反射。但是,在这种模式下,生成的代码仅需要链接到libprotobuf-lite.jar而不是libprotobuf.jar。这个”lite”类库比完全类库小很多,而且更加适合资源受限系统例如移动手机。

Message 接口定义方法让你检查,操纵,读取或者写入完整的消息。在这些方法之外, Foo class定义了下列静态方法:

  • static Foo getDefaultInstance(): 返回Foo的单例实例,这等效于调用Foo.newBuilder().build() (这样所有字段被重置而所有重复字段清空)。注意消息的默认实例可以通过调用它的newBuilderForType()用来作为工厂(factory)。
  • static Descriptor getDescriptor(): 返回类型的描述符。这包含关于类型的信息,包括它有什么字段和他们的类型是什么。这可以和消息的反射方法一起使用,例如 getField().
  • static Foo parseFrom(…): 从给定的资源解析类型 Foo 的消息并返回它。在Message.Builder接口中的mergeFrom()的每个变量有一个对应的parseFrom方法。注意parseFrom()从来不抛出UninitializedMessageException; 如果被解析的消息缺失必要的字段它会抛出InvalidProtocolBufferException。这使得它和调用Foo.newBuilder().mergeFrom(…).build()有微妙的不同。
  • static Parser parser(): 返回解析器实例,它实现了多个parseFrom()方法
  • Foo.Builder newBuilder(): 创建一个新的builder(下面描述).
  • Foo.Builder newBuilder(Foo prototype): 创建一个新的builder,所有字段初始化为和在prototype中一样的值。因为内嵌消息和字符串对象是不可变,他们将会在原始对象和复制对象之间共享。

Builders

Message 对象 - 例如上面描述的 Foo class的实例 - 是不可变的,就像Java字符串。为了构建一个消息对象,需要使用builder。每个message类有它自己的bilder类 - 因此在我们的Foo例子中,protocol buffer编译器生成了一个内嵌类 Foo.Builder 可以用来构建Foo。Foo.Builder实现Message.Builder接口。它继承自GeneratedMessage.Builder类,但是,再次,这应该视为实现细节。和Foo类似,Foo.Builder 可能依靠范型方法实现,或者,当optimize_for选项被使用时,生成的定制化代码要快的多。

Foo.Builder没有定义任何静态方法。它的接口和通过Message.Builder定义的完全一样,不同的是返回类型更加明确:Foo.Builder的方法修改了builder返回类型Foo.Builder,而build()返回类型Foo。

builder的修改内容的方法 - 包括字段setter - 通常返回builder的引用(例如,他们”return this;”)。这容许多个方法调用可以在一行中链起来。例如:

  1. builder.mergeFrom(obj).setFoo(1).setBar("abc").clearBaz();

Sub Builders

对于包含子消息的消息,编译器也生成子builder。这容许你反复修改深层嵌套的子消息而不用重新构建他们。例如:

  1. message Foo {
  2. optional int32 val = 1;
  3. // some other fields.
  4. }
  5. message Bar {
  6. optional Foo foo = 1;
  7. // some other fields.
  8. }
  9. message Baz {
  10. optional Bar bar = 1;
  11. // some other fields.
  12. }

如果你已经有了一个Baz消息,并且想修改深度内嵌的在Foo中的val。以其:

If you have a Baz message already, and want to change the deeply nested val in Foo. Instead of:

  1. baz = baz.toBuilder().setBar(
  2. baz.getBar().toBuilder().setFoo(
  3. baz.getBar().getFoo().toBuilder().setVal(10).build()
  4. ).build()).build();

你可以写:

  1. Baz.Builder builder = baz.toBuilder();
  2. builder.getBarBuilder().getFooBuilder().setVal(10);
  3. baz = builder.build();

内嵌类型

消息可以在其他消息内部定义。例如: message Foo { message Bar { } }

在这种情况下,编译器简单的生成Bar作为内部类内嵌在Foo中。