Reference Guide

GPB is a strongly-typed Interface Definition Language (IDL) with many primitive data types. It also
allows for composite types and namespaces through packages. Users define the type of data they
wish to send/store by defining a protocol file (.proto) that defines the field names, types, default
values, requirements, and other metadata that specifies the content of a given record. [50, 51]
Versioning is controlled in the .proto IDL file through a combination of field numbers and tags
(REQUIRED/OPTIONAL/REPEATED). These tags designate which of the named fields must be
present in a message to be considered valid. There are well-known rules of how to design a .proto
file definition to allow for compatible versions of the data to be sent and received without errors
(see Versioning Rules section that follows).
From the protocol file a provided Java GPB compiler (protoc) then generates the data access
classes for the user’s language of choice. In the generated GPB class, field access and builder
methods are provided for the application to interact with the data. The compiler also enforces the
general version rules of messages to help flag not only syntax and semantic error, but also errors
related to incompatibility between versions of a message.
The application will ultimately use the Model Object it defines and maps to the GPB class that will
be distributed. The conversion from Model Object to GPB object takes place in the custom
serializer the programmer will have to write and register with the Coordination Service to bridge
the object usage in the application and its distribution over the Coordination Services (See
Application GPB Usage section that follows for more details).
Below is an example of a GPB .proto file that defines a Person by their contact information and an
AddressBook by a list of Persons. This example demonstrates the features and syntax of a GPB
message. String and int32 are just two of the 15 definable data types (including enumerated
types) which are similar to existing Java primitive types. Each field requires a tag, type, name, and
number to be valid. Default values are optional. Message structures can be composed of other
messages. In this example we see that a name, id and number are the minimum fields required to
make up a valid Person record. If this were version 1 of the message then, for example, version 2
could include an “optional string website = 5;” field to expand the record further without breaking
compatibility with version 1 of the Person record. The Addressbook message defines a
composition of this Person message to hold a list of people using the repeated tag. [51]
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];
}
76